diff options
Diffstat (limited to 'Documentation/mips')
| -rw-r--r-- | Documentation/mips/GT64120.README | 65 | ||||
| -rw-r--r-- | Documentation/mips/pci/pci.README | 54 | ||||
| -rw-r--r-- | Documentation/mips/time.README | 198 |
3 files changed, 317 insertions, 0 deletions
diff --git a/Documentation/mips/GT64120.README b/Documentation/mips/GT64120.README new file mode 100644 index 00000000000..2d0eec91dc5 --- /dev/null +++ b/Documentation/mips/GT64120.README @@ -0,0 +1,65 @@ +README for arch/mips/gt64120 directory and subdirectories + +Jun Sun, jsun@mvista.com or jsun@junsun.net +01/27, 2001 + +MOTIVATION +---------- + +Many MIPS boards share the same system controller (or CPU companian chip), +such as GT-64120. It is highly desirable to let these boards share +the same controller code instead of duplicating them. + +This directory is meant to hold all MIPS boards that use GT-64120 or GT-64120A. + + +HOW TO ADD A BOARD +------------------ + +. Create a subdirectory include/asm/gt64120/<board>. + +. Create a file called gt64120_dep.h under that directory. + +. Modify include/asm/gt64120/gt64120.h file to include the new gt64120_dep.h + based on config options. The board-dep section is at the end of + include/asm/gt64120/gt64120.h file. There you can find all required + definitions include/asm/gt64120/<board>/gt64120_dep.h file must supply. + +. Create a subdirectory arch/mips/gt64120/<board> directory to hold + board specific routines. + +. The GT-64120 common code is supplied under arch/mips/gt64120/common directory. + It includes: + 1) arch/mips/gt64120/pci.c - + common PCI routine, include the top-level pcibios_init() + 2) arch/mips/gt64120/irq.c - + common IRQ routine, include the top-level do_IRQ() + [This part really belongs to arch/mips/kernel. jsun] + 3) arch/mips/gt64120/gt_irq.c - + common IRQ routines for GT-64120 chip. Currently it only handles + the timer interrupt. + +. Board-specific routines are supplied under arch/mips/gt64120/<board> dir. + 1) arch/mips/gt64120/<board>/pci.c - it provides bus fixup routine + 2) arch/mips/gt64120/<board>/irq.c - it provides enable/disable irqs + and board irq setup routine (irq_setup) + 3) arch/mips/gt64120/<board>/int-handler.S - + The first-level interrupt dispatching routine. + 4) a bunch of other "normal" stuff (setup, prom, dbg_io, reset, etc) + +. Follow other "normal" procedure to modify configuration files, etc. + + +TO-DO LIST +---------- + +. Expand arch/mips/gt64120/gt_irq.c to handle all GT-64120 interrupts. + We probably need to introduce GT_IRQ_BASE in board-dep header file, + which is used the starting irq_nr for all GT irqs. + + A function, gt64120_handle_irq(), will be added so that the first-level + irq dispatcher will call this function if it detects an interrupt + from GT-64120. + +. More support for GT-64120 PCI features (2nd PCI bus, perhaps) + diff --git a/Documentation/mips/pci/pci.README b/Documentation/mips/pci/pci.README new file mode 100644 index 00000000000..8697ee41372 --- /dev/null +++ b/Documentation/mips/pci/pci.README @@ -0,0 +1,54 @@ + +Pete Popov, ppopov@pacbell.net +07/11/2001 + +This README briefly explains how to use the pci and pci_auto +code in arch/mips/kernel. The code was ported from PowerPC and +modified slightly. It has been tested pretty well on PPC on some +rather complex systems with multiple bridges and devices behind +each bridge. However, at the time this README was written, the +mips port was tested only on boards with a single pci bus and +no P2P bridges. It's very possible that on boards with P2P +bridges some modifications have to be made. The code will +evolve, no doubt, but currently every single mips board +is doing its own pcibios thing and it has become a big +mess. This generic pci code is meant to clean up the mips +pci mess and make it easier to add pci support to new boards. + +inside the define for your board in arch/mips/config.in. +For example, the Galileo EV96100 board looks like this: + +if [ "$CONFIG_MIPS_EV96100" = "y" ]; then + define_bool CONFIG_PCI y + define_bool CONFIG_MIPS_GT96100 y + define_bool CONFIG_NEW_PCI y + define_bool CONFIG_SWAP_IO_SPACE y +fi + + +Next, if you want to use the arch/mips/kernel/pci code, which has the +pcibios_init() function, add + +define_bool CONFIG_NEW_PCI y + +inside the define for your board. Again, the EV96100 example above +show NEW_PCI turned on. + + +Now you need to add your files to hook in your pci configuration +cycles. Usually you'll need only a couple of files named something +like pci_fixups.c and pci_ops.c. You can copy the templates +provided and fill in the code. + +The file pci_ops.c should contain the pci configuration cycles routines. +It also has the mips_pci_channels[] array which contains the descriptors +of each pci controller. + +The file pci_fixups.c contains a few routines to do interrupt fixups, +resources fixups, and, if needed, pci bios fixups. + +Usually you'll put your pci_fixups.c file in your board specific directory, +since the functions in that file are board specific. The functions in +pci_ops.c, on the other hand, are usually pci controller specific so that +file could be shared among a few different boards using the same +pci controller. diff --git a/Documentation/mips/time.README b/Documentation/mips/time.README new file mode 100644 index 00000000000..70bc0dd43d6 --- /dev/null +++ b/Documentation/mips/time.README @@ -0,0 +1,198 @@ +README for MIPS time services + +Jun Sun +jsun@mvista.com or jsun@junsun.net + + +ABOUT +----- +This file describes the new arch/mips/kernel/time.c, related files and the +services they provide. + +If you are short in patience and just want to know how to use time.c for a +new board or convert an existing board, go to the last section. + + +FILES, COMPATABILITY AND CONFIGS +--------------------------------- + +The old arch/mips/kernel/time.c is renamed to old-time.c. + +A new time.c is put there, together with include/asm-mips/time.h. + +Two configs variables are introduced, CONFIG_OLD_TIME_C and CONFIG_NEW_TIME_C. +So we allow boards using + + 1) old time.c (CONFIG_OLD_TIME_C) + 2) new time.c (CONFIG_NEW_TIME_C) + 3) neither (their own private time.c) + +However, it is expected every board will move to the new time.c in the near +future. + + +WHAT THE NEW CODE PROVIDES? +--------------------------- + +The new time code provide the following services: + + a) Implements functions required by Linux common code: + time_init + do_gettimeofday + do_settimeofday + + b) provides an abstraction of RTC and null RTC implementation as default. + extern unsigned long (*rtc_get_time)(void); + extern int (*rtc_set_time)(unsigned long); + + c) a set of gettimeoffset functions for different CPUs and different + needs. + + d) high-level and low-level timer interrupt routines where the timer + interrupt source may or may not be the CPU timer. The high-level + routine is dispatched through do_IRQ() while the low-level is + dispatched in assemably code (usually int-handler.S) + + +WHAT THE NEW CODE REQUIRES? +--------------------------- + +For the new code to work properly, each board implementation needs to supply +the following functions or values: + + a) board_time_init - a function pointer. Invoked at the beginnig of + time_init(). It is optional. + 1. (optional) set up RTC routines + 2. (optional) calibrate and set the mips_counter_frequency + + b) board_timer_setup - a function pointer. Invoked at the end of time_init() + 1. (optional) over-ride any decisions made in time_init() + 2. set up the irqaction for timer interrupt. + 3. enable the timer interrupt + + c) (optional) board-specific RTC routines. + + d) (optional) mips_counter_frequency - It must be definied if the board + is using CPU counter for timer interrupt or it is using fixed rate + gettimeoffset(). + + +PORTING GUIDE +------------- + +Step 1: decide how you like to implement the time services. + + a) does this board have a RTC? If yes, implement the two RTC funcs. + + b) does the CPU have counter/compare registers? + + If the answer is no, you need a timer to provide the timer interrupt + at 100 HZ speed. + + You cannot use the fast gettimeoffset functions, i.e., + + unsigned long fixed_rate_gettimeoffset(void); + unsigned long calibrate_div32_gettimeoffset(void); + unsigned long calibrate_div64_gettimeoffset(void); + + You can use null_gettimeoffset() will gives the same time resolution as + jiffy. Or you can implement your own gettimeoffset (probably based on + some ad hoc hardware on your machine.) + + c) The following sub steps assume your CPU has counter register. + Do you plan to use the CPU counter register as the timer interrupt + or use an exnternal timer? + + In order to use CPU counter register as the timer interrupt source, you + must know the counter speed (mips_counter_frequency). It is usually the + same as the CPU speed or an integral divisor of it. + + d) decide on whether you want to use high-level or low-level timer + interrupt routines. The low-level one is presumably faster, but should + not make too mcuh difference. + + +Step 2: the machine setup() function + + If you supply board_time_init(), set the function poointer. + + Set the function pointer board_timer_setup() (mandatory) + + +Step 3: implement rtc routines, board_time_init() and board_timer_setup() + if needed. + + board_time_init() - + a) (optional) set up RTC routines, + b) (optional) calibrate and set the mips_counter_frequency + (only needed if you intended to use fixed_rate_gettimeoffset + or use cpu counter as timer interrupt source) + + board_timer_setup() - + a) (optional) over-write any choices made above by time_init(). + b) machine specific code should setup the timer irqaction. + c) enable the timer interrupt + + + If the RTC chip is a common chip, I suggest the routines are put under + arch/mips/libs. For example, for DS1386 chip, one would create + rtc-ds1386.c under arch/mips/lib directory. Add the following line to + the arch/mips/lib/Makefile: + + obj-$(CONFIG_DDB5476) += rtc-ds1386.o + +Step 4: if you are using low-level timer interrupt, change your interrupt + dispathcing code to check for timer interrupt and jump to + ll_timer_interrupt() directly if one is detected. + +Step 5: Modify arch/mips/config.in and add CONFIG_NEW_TIME_C to your machine. + Modify the appropriate defconfig if applicable. + +Final notes: + +For some tricky cases, you may need to add your own wrapper functions +for some of the functions in time.c. + +For example, you may define your own timer interrupt routine, which does +some of its own processing and then calls timer_interrupt(). + +You can also over-ride any of the built-in functions (gettimeoffset, +RTC routines and/or timer interrupt routine). + + +PORTING NOTES FOR SMP +---------------------- + +If you have a SMP box, things are slightly more complicated. + +The time service running every jiffy is logically divided into two parts: + + 1) the one for the whole system (defined in timer_interrupt()) + 2) the one that should run for each CPU (defined in local_timer_interrupt()) + +You need to decide on your timer interrupt sources. + + case 1) - whole system has only one timer interrupt delivered to one CPU + + In this case, you set up timer interrupt as in UP systems. In addtion, + you need to set emulate_local_timer_interrupt to 1 so that other + CPUs get to call local_timer_interrupt(). + + THIS IS CURRENTLY NOT IMPLEMNETED. However, it is rather easy to write + one should such a need arise. You simply make a IPI call. + + case 2) - each CPU has a separate timer interrupt + + In this case, you need to set up IRQ such that each of them will + call local_timer_interrupt(). In addition, you need to arrange + one and only one of them to call timer_interrupt(). + + You can also do the low-level version of those interrupt routines, + following similar dispatching routes described above. + +Note about do_gettimeoffset(): + + It is very likely the CPU counter registers are not sync'ed up in a SMP box. + Therefore you cannot really use the many of the existing routines that + are based on CPU counter. You should wirte your own gettimeoffset rouinte + if you want intra-jiffy resolution. |