saving added docu

5 files changed, 216 insertions, 30 deletions

diff --git a/arch/architecture.dox b/arch/architecture.dox
index 85cff53ed7..3f94b3c321 100644
--- a/arch/architecture.dox
+++ b/arch/architecture.dox
@@ -1,6 +1,33 @@
 /** @page dev_architecture Integrate a new architecture (ARCH)
 
-Friesel
+@section linker_scripts Rules for the generic Linker Script File
+
+Never include an object file by name directly! Linker Script Files defines the
+layout, not the content. Content is defined in objecfiles instead.
+
+Don't rely on the given object file order to create your binary U-Boot v2! This
+may work, but is not relyable in all cases (and its a very bad style)!
+
+For the special case some layout contraints exists, use specific section
+naming instead. Refer @ref reset_code how to define this specific section.
+
+@section reset_code Bring it up: The Reset Code
+
+The way a CPU wakes up after reset is very specific to its architecture.
+
+For example the ARM architecture starts its reset code at address 0x0000000,
+the x86 architecture at 0x000FFFF0, PowerPC at 0x00000100 or 0xFFFFF100.
+
+So for the special reset code on all architectures it must be located at
+architecture specific locations within the binary U-Boot image.
+
+All reset code uses section ".text_entry" for its localisation within the
+binary U-Boot image. Its up to the linker script file to use this section name
+to find the right place in whatever environment and U-Boot sizes.
+
+@code
+	.section ".text_entry","ax"
+@endcode
 
 */
 
diff --git a/arch/arm/cpu/cpu.c b/arch/arm/cpu/cpu.c
index e2b31edec5..d79d4ce539 100644
--- a/arch/arm/cpu/cpu.c
+++ b/arch/arm/cpu/cpu.c
@@ -1,7 +1,37 @@
+/*
+ * cpu.c - A few helper functions for ARM
+ *
+ * Copyright (c) 2007 Sascha Hauer <s.hauer@pengutronix.de>, Pengutronix
+ *
+ * See file CREDITS for list of people who contributed to this
+ * project.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/**
+ * @file
+ * @brief A few helper functions for ARM
+ */
+
 #include <common.h>
 #include <command.h>
 
-/* read co-processor 15, register #1 (control register) */
+/**
+ * Read special processor register
+ * @return co-processor 15, register #1 (control register)
+ */
 static unsigned long read_p15_c1 (void)
 {
 	unsigned long value;
@@ -18,7 +48,12 @@ static unsigned long read_p15_c1 (void)
 	return value;
 }
 
-/* write to co-processor 15, register #1 (control register) */
+/**
+ *
+ * Write special processor register
+ * @param[in] value to write
+ * @return to co-processor 15, register #1 (control register)
+ */
 static void write_p15_c1 (unsigned long value)
 {
 #ifdef MMU_DEBUG
@@ -33,23 +68,38 @@ static void write_p15_c1 (unsigned long value)
 	read_p15_c1 ();
 }
 
+/**
+ * Wait for co prozessor (waste time)
+ * Co processor seems to need some delay between accesses
+ */
 static void cp_delay (void)
 {
 	volatile int i;
 
-	/* copro seems to need some delay between reading and writing */
-	for (i = 0; i < 100; i++);
+	for (i = 0; i < 100; i++)	/* FIXME does it work as expected?? */
+		;
 }
 
-#define C1_MMU		(1<<0)		/* mmu off/on */
-#define C1_ALIGN	(1<<1)		/* alignment faults off/on */
-#define C1_DC		(1<<2)		/* dcache off/on */
-#define C1_BIG_ENDIAN	(1<<7)		/* big endian off/on */
-#define C1_SYS_PROT	(1<<8)		/* system protection */
-#define C1_ROM_PROT	(1<<9)		/* ROM protection */
-#define C1_IC		(1<<12)		/* icache off/on */
-#define C1_HIGH_VECTORS (1<<13)		/* location of vectors: low/high addresses */
-
+/** mmu off/on */
+#define C1_MMU		(1<<0)
+/** alignment faults off/on */
+#define C1_ALIGN	(1<<1)
+/** dcache off/on */
+#define C1_DC		(1<<2)
+/** big endian off/on */
+#define C1_BIG_ENDIAN	(1<<7)
+/** system protection */
+#define C1_SYS_PROT	(1<<8)
+/** ROM protection */
+#define C1_ROM_PROT	(1<<9)
+/** icache off/on */
+#define C1_IC		(1<<12)
+/** location of vectors: low/high addresses */
+#define C1_HIGH_VECTORS (1<<13)
+
+/**
+ * Enable processor's instruction cache
+ */
 void icache_enable (void)
 {
 	ulong reg;
@@ -59,6 +109,9 @@ void icache_enable (void)
 	write_p15_c1 (reg | C1_IC);
 }
 
+/**
+ * Disable processor's instruction cache
+ */
 void icache_disable (void)
 {
 	ulong reg;
@@ -68,30 +121,39 @@ void icache_disable (void)
 	write_p15_c1 (reg & ~C1_IC);
 }
 
+/**
+ * Detect processor's current instruction cache status
+ * @return 0=disabled, 1=enabled
+ */
 int icache_status (void)
 {
 	return (read_p15_c1 () & C1_IC) != 0;
 }
 
-/*
- * this function is called just before we call linux
- * it prepares the processor for linux
+/**
+ * Prepare a "clean" CPU for Linux to run
+ * @return 0 (always)
+ *
+ * This function is called by the generic U-Boot part just before we call
+ * Linux. It prepares the processor for Linux.
  */
 int cleanup_before_linux (void)
 {
 	int i;
 
-	/*
-	 * we never enable dcache so we do not need to disable
-	 * it. Linux can be called with icache enabled, so just
-	 * do nothing here
-	 */
-
 	/* flush I/D-cache */
 	i = 0;
 	asm ("mcr p15, 0, %0, c7, c7, 0": :"r" (i));
 	return (0);
 }
+/**
+ * @page arm_boot_preparation Linux Preparation on ARM
+ *
+ * For ARM we never enable data cache so we do not need to disable it again.
+ * Linux can be called with instruction cache enabled. As this is the
+ * default setting we are running in U-Boot, there's no special preparation
+ * required.
+ */
 
 #ifdef CONFIG_USE_IRQ
 static int cpu_init (void)
@@ -106,3 +168,9 @@ static int cpu_init (void)
 
 core_initcall(cpu_init);
 #endif
+
+/**
+ * @page arm_for_linux Preparing for Linux to run
+ *
+ * What's to do on ARM to run Linux after U-Boot did its job?
+ */
\ No newline at end of file
diff --git a/arch/arm/cpu/interrupts.c b/arch/arm/cpu/interrupts.c
index 23f8b3f029..418da18b44 100644
--- a/arch/arm/cpu/interrupts.c
+++ b/arch/arm/cpu/interrupts.c
@@ -1,3 +1,30 @@
+/*
+ * interrupts.c - Interrupt Support Routines
+ *
+ * Copyright (c) 2007 Sascha Hauer <s.hauer@pengutronix.de>, Pengutronix
+ *
+ * See file CREDITS for list of people who contributed to this
+ * project.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/**
+ * @file
+ * @brief Interrupt Support Routines
+ */
+
 #include <common.h>
 #include <asm/ptrace.h>
 
@@ -32,12 +59,19 @@ int disable_interrupts (void)
 }
 #endif
 
+/**
+ * FIXME
+ */
 void bad_mode (void)
 {
 	panic ("Resetting CPU ...\n");
 	reset_cpu (0);
 }
 
+/**
+ * Display current register set content
+ * @param[in] regs Guess what
+ */
 void show_regs (struct pt_regs *regs)
 {
 	unsigned long flags;
@@ -75,6 +109,10 @@ void show_regs (struct pt_regs *regs)
 		thumb_mode (regs) ? " (T)" : "");
 }
 
+/**
+ * The CPU runs into an undefined instruction. That really should not happen!
+ * @param[in] pt_regs Register set content when the accident happens
+ */
 void do_undefined_instruction (struct pt_regs *pt_regs)
 {
 	printf ("undefined instruction\n");
@@ -82,6 +120,13 @@ void do_undefined_instruction (struct pt_regs *pt_regs)
 	bad_mode ();
 }
 
+/**
+ * The CPU catches a software interrupt
+ * @param[in] pt_regs Register set content when the interrupt happens
+ *
+ * There is not functione behind this feature. So what to do else than
+ * a reset? 
+ */
 void do_software_interrupt (struct pt_regs *pt_regs)
 {
 	printf ("software interrupt\n");
@@ -89,6 +134,12 @@ void do_software_interrupt (struct pt_regs *pt_regs)
 	bad_mode ();
 }
 
+/**
+ * The CPU catches a prefetch abort. That really should not happen!
+ * @param[in] pt_regs Register set content when the accident happens
+ *
+ * FIXME: What does it mean, why is reset the only solution?
+ */
 void do_prefetch_abort (struct pt_regs *pt_regs)
 {
 	printf ("prefetch abort\n");
@@ -96,6 +147,12 @@ void do_prefetch_abort (struct pt_regs *pt_regs)
 	bad_mode ();
 }
 
+/**
+ * The CPU catches a data abort. That really should not happen!
+ * @param[in] pt_regs Register set content when the accident happens
+ *
+ * FIXME: What does it mean, why is reset the only solution?
+ */
 void do_data_abort (struct pt_regs *pt_regs)
 {
 	printf ("data abort\n");
@@ -103,6 +160,12 @@ void do_data_abort (struct pt_regs *pt_regs)
 	bad_mode ();
 }
 
+/**
+ * The CPU catches a not-used(?) abort.
+ * @param[in] pt_regs Register set content when the accident happens
+ *
+ * FIXME: What does it mean, why is reset the only solution?
+ */
 void do_not_used (struct pt_regs *pt_regs)
 {
 	printf ("not used\n");
@@ -110,6 +173,12 @@ void do_not_used (struct pt_regs *pt_regs)
 	bad_mode ();
 }
 
+/**
+ * The CPU catches a fast interrupt request.
+ * @param[in] pt_regs Register set content when the interrupt happens
+ *
+ * FIXME: What does it mean, why is reset the only solution?
+ */
 void do_fiq (struct pt_regs *pt_regs)
 {
 	printf ("fast interrupt request\n");
@@ -117,9 +186,21 @@ void do_fiq (struct pt_regs *pt_regs)
 	bad_mode ();
 }
 
+/**
+ * The CPU catches a regular interrupt.
+ * @param[in] pt_regs Register set content when the interrupt happens
+ *
+ * FIXME: What does it mean, why is reset the only solution?
+ */
 void do_irq (struct pt_regs *pt_regs)
 {
 	printf ("interrupt request\n");
 	show_regs (pt_regs);
 	bad_mode ();
 }
+
+/**
+ * @page arm_interrupts Interrupt handling on ARM
+ *
+ * Why U-boot doesn't use interrupts?
+ */
diff --git a/arch/arm/cpu/start-arm920t.S b/arch/arm/cpu/start-arm920t.S
index eed1364e3a..db52ad9ed8 100644
--- a/arch/arm/cpu/start-arm920t.S
+++ b/arch/arm/cpu/start-arm920t.S
@@ -24,13 +24,18 @@
  * MA 02111-1307 USA
  */
 
-/*
- * Note:
- * This file can be used for at least:
- * - ARM920T
- * - i.MX1
- * - i.MX27
- * - i.MX31
+/**
+ * @file
+ * @brief The very basic beginning of each CPU after reset
+ *
+ * @note
+ * This reset code can be used at least for:
+ *  - ARM920T
+ *  - i.MX1
+ *  - i.MX27
+ *  - i.MX31
+ *
+ * FIXME: Stop doxygen from parsing the text below
  */
 	.section ".text_entry","ax"
 
diff --git a/arch/sandbox/lib/tap.c b/arch/sandbox/lib/tap.c
index b620612626..ebd828b2b2 100644
--- a/arch/sandbox/lib/tap.c
+++ b/arch/sandbox/lib/tap.c
@@ -61,3 +61,8 @@ int tap_alloc(char *dev)
 	strcpy(dev, ifr.ifr_name);
 	return fd;
 }
+
+/**
+ * @file
+ * @brief Host side functions for tap driver
+ */