From 645d26aca3348c8e0fd3c764ce17dab29bd22584 Mon Sep 17 00:00:00 2001
From: Antony Pavlov <antonynpavlov@gmail.com>
Date: Fri, 5 Aug 2011 14:58:35 +0400
Subject: [PATCH] MIPS: add documentation

Signed-off-by: Antony Pavlov <antonynpavlov@gmail.com>
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
---
 arch/architecture.dox   |  1 +
 arch/mips/mach-mips.dox | 54 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 arch/mips/mach-mips.dox

diff --git a/arch/architecture.dox b/arch/architecture.dox
index 67e2c3886..2d2cf05aa 100644
--- a/arch/architecture.dox
+++ b/arch/architecture.dox
@@ -86,6 +86,7 @@ TODO
 
 @li @subpage dev_arm_mach
 @li @subpage dev_bf_mach
+@li @subpage dev_mips_mach
 @li @subpage dev_ppc_mach
 @li @subpage dev_x86_mach
 
diff --git a/arch/mips/mach-mips.dox b/arch/mips/mach-mips.dox
new file mode 100644
index 000000000..018fc4483
--- /dev/null
+++ b/arch/mips/mach-mips.dox
@@ -0,0 +1,54 @@
+/* This document is intended to provide the developer with information
+ * how to integrate a new CPU (MACH) into this part of the barebox tree
+ */
+
+/** @page dev_mips_mach MIPS based CPU (MACH) into the tree
+
+@section mach_mips_reset What's happens when the reset signal is gone
+
+Barebox normally must be linked to RAM region, cached region KSEG0 is preferred.
+This make possible to run fast (because cache used) and skip MMU support.
+
+After reset MIPS CPU starting to fetch instructions from 0xBFC00000.
+
+@note Code running immediately after reset runs at an address it is not linked
+      to: "runtime address != link address". You should only use branches and
+      do not refer to fixed data. This implies the use of assembler code only.
+      After MIPS CPU reset cache and MMU are in random state. They are unusable.
+
+barebox MIPS initialisation sequence:
+
+ * set the CP0 STATUS register to some known and sensible state.
+Now you can load and store reliably in uncached space.
+
+ * call a function \<mach_init_lowlevel\> (if not disabled).
+do some special things required only on specific CPU
+ (e. g. init RAM controller, disable watchdog)
+
+ * call a function \<board_init_lowlevel\> (if not disable).
+do some special things required only on specific board
+ (e. g. setup GPIO to required state).
+
+   ** It is desirable to have some debug code to make some contact
+ with the outside world from assembler code
+(e.g. debug_ll-like functions to write to rs232 console).
+
+ * check integrity of barebox RAM execute location;
+ * copy barebox to RAM execute location;
+
+ * configure cache;
+
+ * setup stack;
+
+   ** after this point you can call a standard C routine.
+
+ * setup exception vectors in RAM;
+ * setup CP0 STATUS to switch exception vector address to RAM;
+
+ * call start_barebox()
+
+Further reading:
+ * Dominic Sweetman, See MIPS Run, Morgan Kaufmann, 2nd edition, 2006
+ISBN-13: 978-0120884216
+
+*/