diff options
author | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 18:20:36 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 18:20:36 -0400 |
commit | 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch) | |
tree | 0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/mips/time.README |
Linux-2.6.12-rc2v2.6.12-rc2
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.
Let it rip!
Diffstat (limited to 'Documentation/mips/time.README')
-rw-r--r-- | Documentation/mips/time.README | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/Documentation/mips/time.README b/Documentation/mips/time.README new file mode 100644 index 000000000000..70bc0dd43d6d --- /dev/null +++ b/Documentation/mips/time.README | |||
@@ -0,0 +1,198 @@ | |||
1 | README for MIPS time services | ||
2 | |||
3 | Jun Sun | ||
4 | jsun@mvista.com or jsun@junsun.net | ||
5 | |||
6 | |||
7 | ABOUT | ||
8 | ----- | ||
9 | This file describes the new arch/mips/kernel/time.c, related files and the | ||
10 | services they provide. | ||
11 | |||
12 | If you are short in patience and just want to know how to use time.c for a | ||
13 | new board or convert an existing board, go to the last section. | ||
14 | |||
15 | |||
16 | FILES, COMPATABILITY AND CONFIGS | ||
17 | --------------------------------- | ||
18 | |||
19 | The old arch/mips/kernel/time.c is renamed to old-time.c. | ||
20 | |||
21 | A new time.c is put there, together with include/asm-mips/time.h. | ||
22 | |||
23 | Two configs variables are introduced, CONFIG_OLD_TIME_C and CONFIG_NEW_TIME_C. | ||
24 | So we allow boards using | ||
25 | |||
26 | 1) old time.c (CONFIG_OLD_TIME_C) | ||
27 | 2) new time.c (CONFIG_NEW_TIME_C) | ||
28 | 3) neither (their own private time.c) | ||
29 | |||
30 | However, it is expected every board will move to the new time.c in the near | ||
31 | future. | ||
32 | |||
33 | |||
34 | WHAT THE NEW CODE PROVIDES? | ||
35 | --------------------------- | ||
36 | |||
37 | The new time code provide the following services: | ||
38 | |||
39 | a) Implements functions required by Linux common code: | ||
40 | time_init | ||
41 | do_gettimeofday | ||
42 | do_settimeofday | ||
43 | |||
44 | b) provides an abstraction of RTC and null RTC implementation as default. | ||
45 | extern unsigned long (*rtc_get_time)(void); | ||
46 | extern int (*rtc_set_time)(unsigned long); | ||
47 | |||
48 | c) a set of gettimeoffset functions for different CPUs and different | ||
49 | needs. | ||
50 | |||
51 | d) high-level and low-level timer interrupt routines where the timer | ||
52 | interrupt source may or may not be the CPU timer. The high-level | ||
53 | routine is dispatched through do_IRQ() while the low-level is | ||
54 | dispatched in assemably code (usually int-handler.S) | ||
55 | |||
56 | |||
57 | WHAT THE NEW CODE REQUIRES? | ||
58 | --------------------------- | ||
59 | |||
60 | For the new code to work properly, each board implementation needs to supply | ||
61 | the following functions or values: | ||
62 | |||
63 | a) board_time_init - a function pointer. Invoked at the beginnig of | ||
64 | time_init(). It is optional. | ||
65 | 1. (optional) set up RTC routines | ||
66 | 2. (optional) calibrate and set the mips_counter_frequency | ||
67 | |||
68 | b) board_timer_setup - a function pointer. Invoked at the end of time_init() | ||
69 | 1. (optional) over-ride any decisions made in time_init() | ||
70 | 2. set up the irqaction for timer interrupt. | ||
71 | 3. enable the timer interrupt | ||
72 | |||
73 | c) (optional) board-specific RTC routines. | ||
74 | |||
75 | d) (optional) mips_counter_frequency - It must be definied if the board | ||
76 | is using CPU counter for timer interrupt or it is using fixed rate | ||
77 | gettimeoffset(). | ||
78 | |||
79 | |||
80 | PORTING GUIDE | ||
81 | ------------- | ||
82 | |||
83 | Step 1: decide how you like to implement the time services. | ||
84 | |||
85 | a) does this board have a RTC? If yes, implement the two RTC funcs. | ||
86 | |||
87 | b) does the CPU have counter/compare registers? | ||
88 | |||
89 | If the answer is no, you need a timer to provide the timer interrupt | ||
90 | at 100 HZ speed. | ||
91 | |||
92 | You cannot use the fast gettimeoffset functions, i.e., | ||
93 | |||
94 | unsigned long fixed_rate_gettimeoffset(void); | ||
95 | unsigned long calibrate_div32_gettimeoffset(void); | ||
96 | unsigned long calibrate_div64_gettimeoffset(void); | ||
97 | |||
98 | You can use null_gettimeoffset() will gives the same time resolution as | ||
99 | jiffy. Or you can implement your own gettimeoffset (probably based on | ||
100 | some ad hoc hardware on your machine.) | ||
101 | |||
102 | c) The following sub steps assume your CPU has counter register. | ||
103 | Do you plan to use the CPU counter register as the timer interrupt | ||
104 | or use an exnternal timer? | ||
105 | |||
106 | In order to use CPU counter register as the timer interrupt source, you | ||
107 | must know the counter speed (mips_counter_frequency). It is usually the | ||
108 | same as the CPU speed or an integral divisor of it. | ||
109 | |||
110 | d) decide on whether you want to use high-level or low-level timer | ||
111 | interrupt routines. The low-level one is presumably faster, but should | ||
112 | not make too mcuh difference. | ||
113 | |||
114 | |||
115 | Step 2: the machine setup() function | ||
116 | |||
117 | If you supply board_time_init(), set the function poointer. | ||
118 | |||
119 | Set the function pointer board_timer_setup() (mandatory) | ||
120 | |||
121 | |||
122 | Step 3: implement rtc routines, board_time_init() and board_timer_setup() | ||
123 | if needed. | ||
124 | |||
125 | board_time_init() - | ||
126 | a) (optional) set up RTC routines, | ||
127 | b) (optional) calibrate and set the mips_counter_frequency | ||
128 | (only needed if you intended to use fixed_rate_gettimeoffset | ||
129 | or use cpu counter as timer interrupt source) | ||
130 | |||
131 | board_timer_setup() - | ||
132 | a) (optional) over-write any choices made above by time_init(). | ||
133 | b) machine specific code should setup the timer irqaction. | ||
134 | c) enable the timer interrupt | ||
135 | |||
136 | |||
137 | If the RTC chip is a common chip, I suggest the routines are put under | ||
138 | arch/mips/libs. For example, for DS1386 chip, one would create | ||
139 | rtc-ds1386.c under arch/mips/lib directory. Add the following line to | ||
140 | the arch/mips/lib/Makefile: | ||
141 | |||
142 | obj-$(CONFIG_DDB5476) += rtc-ds1386.o | ||
143 | |||
144 | Step 4: if you are using low-level timer interrupt, change your interrupt | ||
145 | dispathcing code to check for timer interrupt and jump to | ||
146 | ll_timer_interrupt() directly if one is detected. | ||
147 | |||
148 | Step 5: Modify arch/mips/config.in and add CONFIG_NEW_TIME_C to your machine. | ||
149 | Modify the appropriate defconfig if applicable. | ||
150 | |||
151 | Final notes: | ||
152 | |||
153 | For some tricky cases, you may need to add your own wrapper functions | ||
154 | for some of the functions in time.c. | ||
155 | |||
156 | For example, you may define your own timer interrupt routine, which does | ||
157 | some of its own processing and then calls timer_interrupt(). | ||
158 | |||
159 | You can also over-ride any of the built-in functions (gettimeoffset, | ||
160 | RTC routines and/or timer interrupt routine). | ||
161 | |||
162 | |||
163 | PORTING NOTES FOR SMP | ||
164 | ---------------------- | ||
165 | |||
166 | If you have a SMP box, things are slightly more complicated. | ||
167 | |||
168 | The time service running every jiffy is logically divided into two parts: | ||
169 | |||
170 | 1) the one for the whole system (defined in timer_interrupt()) | ||
171 | 2) the one that should run for each CPU (defined in local_timer_interrupt()) | ||
172 | |||
173 | You need to decide on your timer interrupt sources. | ||
174 | |||
175 | case 1) - whole system has only one timer interrupt delivered to one CPU | ||
176 | |||
177 | In this case, you set up timer interrupt as in UP systems. In addtion, | ||
178 | you need to set emulate_local_timer_interrupt to 1 so that other | ||
179 | CPUs get to call local_timer_interrupt(). | ||
180 | |||
181 | THIS IS CURRENTLY NOT IMPLEMNETED. However, it is rather easy to write | ||
182 | one should such a need arise. You simply make a IPI call. | ||
183 | |||
184 | case 2) - each CPU has a separate timer interrupt | ||
185 | |||
186 | In this case, you need to set up IRQ such that each of them will | ||
187 | call local_timer_interrupt(). In addition, you need to arrange | ||
188 | one and only one of them to call timer_interrupt(). | ||
189 | |||
190 | You can also do the low-level version of those interrupt routines, | ||
191 | following similar dispatching routes described above. | ||
192 | |||
193 | Note about do_gettimeoffset(): | ||
194 | |||
195 | It is very likely the CPU counter registers are not sync'ed up in a SMP box. | ||
196 | Therefore you cannot really use the many of the existing routines that | ||
197 | are based on CPU counter. You should wirte your own gettimeoffset rouinte | ||
198 | if you want intra-jiffy resolution. | ||