Commit 6f75aaa72af19d3e4d144e13d59e71f51686b77f
1 parent
1d9ef3ecd7
Exists in
master
and in
20 other branches
[MIPS] Delete totally outdated Documentation/mips/time.README
Signed-off-by: Ralf Baechle <ralf@linux-mips.org>
Showing 2 changed files with 0 additions and 175 deletions Side-by-side Diff
Documentation/mips/00-INDEX
Documentation/mips/time.README
| 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 | - | |
| 42 | - b) provides an abstraction of RTC and null RTC implementation as default. | |
| 43 | - extern unsigned long (*rtc_get_time)(void); | |
| 44 | - extern int (*rtc_set_time)(unsigned long); | |
| 45 | - | |
| 46 | - c) high-level and low-level timer interrupt routines where the timer | |
| 47 | - interrupt source may or may not be the CPU timer. The high-level | |
| 48 | - routine is dispatched through do_IRQ() while the low-level is | |
| 49 | - dispatched in assemably code (usually int-handler.S) | |
| 50 | - | |
| 51 | - | |
| 52 | -WHAT THE NEW CODE REQUIRES? | |
| 53 | ---------------------------- | |
| 54 | - | |
| 55 | -For the new code to work properly, each board implementation needs to supply | |
| 56 | -the following functions or values: | |
| 57 | - | |
| 58 | - a) board_time_init - a function pointer. Invoked at the beginnig of | |
| 59 | - time_init(). It is optional. | |
| 60 | - 1. (optional) set up RTC routines | |
| 61 | - 2. (optional) calibrate and set the mips_hpt_frequency | |
| 62 | - | |
| 63 | - b) plat_timer_setup - a function pointer. Invoked at the end of time_init() | |
| 64 | - 1. (optional) over-ride any decisions made in time_init() | |
| 65 | - 2. set up the irqaction for timer interrupt. | |
| 66 | - 3. enable the timer interrupt | |
| 67 | - | |
| 68 | - c) (optional) board-specific RTC routines. | |
| 69 | - | |
| 70 | - d) (optional) mips_hpt_frequency - It must be definied if the board | |
| 71 | - is using CPU counter for timer interrupt. | |
| 72 | - | |
| 73 | - | |
| 74 | -PORTING GUIDE | |
| 75 | -------------- | |
| 76 | - | |
| 77 | -Step 1: decide how you like to implement the time services. | |
| 78 | - | |
| 79 | - a) does this board have a RTC? If yes, implement the two RTC funcs. | |
| 80 | - | |
| 81 | - b) does the CPU have counter/compare registers? | |
| 82 | - | |
| 83 | - If the answer is no, you need a timer to provide the timer interrupt | |
| 84 | - at 100 HZ speed. | |
| 85 | - | |
| 86 | - c) The following sub steps assume your CPU has counter register. | |
| 87 | - Do you plan to use the CPU counter register as the timer interrupt | |
| 88 | - or use an exnternal timer? | |
| 89 | - | |
| 90 | - In order to use CPU counter register as the timer interrupt source, you | |
| 91 | - must know the counter speed (mips_hpt_frequency). It is usually the | |
| 92 | - same as the CPU speed or an integral divisor of it. | |
| 93 | - | |
| 94 | - d) decide on whether you want to use high-level or low-level timer | |
| 95 | - interrupt routines. The low-level one is presumably faster, but should | |
| 96 | - not make too mcuh difference. | |
| 97 | - | |
| 98 | - | |
| 99 | -Step 2: the machine setup() function | |
| 100 | - | |
| 101 | - If you supply board_time_init(), set the function poointer. | |
| 102 | - | |
| 103 | - | |
| 104 | -Step 3: implement rtc routines, board_time_init() and plat_timer_setup() | |
| 105 | - if needed. | |
| 106 | - | |
| 107 | - board_time_init() - | |
| 108 | - a) (optional) set up RTC routines, | |
| 109 | - b) (optional) calibrate and set the mips_hpt_frequency | |
| 110 | - (only needed if you intended to use cpu counter as timer interrupt | |
| 111 | - source) | |
| 112 | - | |
| 113 | - plat_timer_setup() - | |
| 114 | - a) (optional) over-write any choices made above by time_init(). | |
| 115 | - b) machine specific code should setup the timer irqaction. | |
| 116 | - c) enable the timer interrupt | |
| 117 | - | |
| 118 | - | |
| 119 | - If the RTC chip is a common chip, I suggest the routines are put under | |
| 120 | - arch/mips/libs. For example, for DS1386 chip, one would create | |
| 121 | - rtc-ds1386.c under arch/mips/lib directory. Add the following line to | |
| 122 | - the arch/mips/lib/Makefile: | |
| 123 | - | |
| 124 | - obj-$(CONFIG_DDB5476) += rtc-ds1386.o | |
| 125 | - | |
| 126 | -Step 4: if you are using low-level timer interrupt, change your interrupt | |
| 127 | - dispathcing code to check for timer interrupt and jump to | |
| 128 | - ll_timer_interrupt() directly if one is detected. | |
| 129 | - | |
| 130 | -Step 5: Modify arch/mips/config.in and add CONFIG_NEW_TIME_C to your machine. | |
| 131 | - Modify the appropriate defconfig if applicable. | |
| 132 | - | |
| 133 | -Final notes: | |
| 134 | - | |
| 135 | -For some tricky cases, you may need to add your own wrapper functions | |
| 136 | -for some of the functions in time.c. | |
| 137 | - | |
| 138 | -For example, you may define your own timer interrupt routine, which does | |
| 139 | -some of its own processing and then calls timer_interrupt(). | |
| 140 | - | |
| 141 | -You can also over-ride any of the built-in functions (RTC routines | |
| 142 | -and/or timer interrupt routine). | |
| 143 | - | |
| 144 | - | |
| 145 | -PORTING NOTES FOR SMP | |
| 146 | ----------------------- | |
| 147 | - | |
| 148 | -If you have a SMP box, things are slightly more complicated. | |
| 149 | - | |
| 150 | -The time service running every jiffy is logically divided into two parts: | |
| 151 | - | |
| 152 | - 1) the one for the whole system (defined in timer_interrupt()) | |
| 153 | - 2) the one that should run for each CPU (defined in local_timer_interrupt()) | |
| 154 | - | |
| 155 | -You need to decide on your timer interrupt sources. | |
| 156 | - | |
| 157 | - case 1) - whole system has only one timer interrupt delivered to one CPU | |
| 158 | - | |
| 159 | - In this case, you set up timer interrupt as in UP systems. In addtion, | |
| 160 | - you need to set emulate_local_timer_interrupt to 1 so that other | |
| 161 | - CPUs get to call local_timer_interrupt(). | |
| 162 | - | |
| 163 | - THIS IS CURRENTLY NOT IMPLEMNETED. However, it is rather easy to write | |
| 164 | - one should such a need arise. You simply make a IPI call. | |
| 165 | - | |
| 166 | - case 2) - each CPU has a separate timer interrupt | |
| 167 | - | |
| 168 | - In this case, you need to set up IRQ such that each of them will | |
| 169 | - call local_timer_interrupt(). In addition, you need to arrange | |
| 170 | - one and only one of them to call timer_interrupt(). | |
| 171 | - | |
| 172 | - You can also do the low-level version of those interrupt routines, | |
| 173 | - following similar dispatching routes described above. |