summaryrefslogtreecommitdiff
path: root/Documentation/mips
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 15:20:36 -0700
committerLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 15:20:36 -0700
commit1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch)
tree0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/mips
Linux-2.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')
-rw-r--r--Documentation/mips/GT64120.README65
-rw-r--r--Documentation/mips/pci/pci.README54
-rw-r--r--Documentation/mips/time.README198
3 files changed, 317 insertions, 0 deletions
diff --git a/Documentation/mips/GT64120.README b/Documentation/mips/GT64120.README
new file mode 100644
index 000000000000..2d0eec91dc59
--- /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 000000000000..8697ee41372d
--- /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 000000000000..70bc0dd43d6d
--- /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.