Various cosmetic fixes, added Doxygen comments (trivial).

Signed-off-by: Uwe Hermann <uwe@hermann-uwe.de>
Acked-by: Uwe Hermann <uwe@hermann-uwe.de>



git-svn-id: svn://coreboot.org/repository/coreboot-v3@634 f3766cd6-281f-0410-b1cd-43a5c92072e9

lib/ram.c

@@ -33,10 +33,11 @@ void ram_failure(const char *why)
 	hlt();
 }
 
-/* Northbridge or memory controller code must define these functions */
+/* Northbridge or memory controller code must define these functions. */
 void ram_set_registers(void *ctrl, int i);
 int ram_set_spd_registers(void *ctrl, int i);
 void ram_enable(int controllers, void *ctrl);
+
 /**
  * ram_initialize() is is the main RAM init function.
  *
@@ -45,10 +46,11 @@ void ram_enable(int controllers, void *ctrl);
  * of making it an empty function.
  *
  * @param controllers How many memory controllers there are.
- * @param ctrl Pointer to the mem control structure. This is a generic pointer, since the 
+ * @param ctrl Pointer to the mem control structure. This is a generic pointer,
- *    structure is wholly chip-dependent, and a survey of all the types makes it clear that a common 
+ *             since the structure is wholly chip-dependent, and a survey of
- *    struct is not possible. We can not use the device tree here as this code is run before the device tree
+ *             all the types makes it clear that a common struct is not
- *    is available. 
+ *             possible. We can not use the device tree here as this code is
+ *             run before the device tree is available. 
  */
 void ram_initialize(int controllers, void *ctrl)
 {
@@ -61,10 +63,10 @@ void ram_initialize(int controllers, void *ctrl)
 		ram_set_registers(ctrl, i);
 	}
 
-	/* Now setup those things we can auto detect. */
+	/* Now setup those things we can auto-detect via SPD. */
 	for (i = 0; i < controllers; i++) {
 		printk(BIOS_INFO,
-		  "Setting SPD based registers of RAM controller %d\n", i);
+		       "Setting SPD based registers of RAM controller %d\n", i);
 		ram_set_spd_registers(ctrl, i);
 	}
 

lib/ramtest.c

@@ -23,7 +23,12 @@
 #include <lib.h>
 #include <console.h>
 
-
+/**
+ * Write a value into memory.
+ *
+ * @param addr The memory address to write to.
+ * @param value The value to write into the specified memory address.
+ */
 static void write_phys(unsigned long addr, unsigned long value)
 {
 	volatile unsigned long *ptr;
@@ -31,6 +36,12 @@ static void write_phys(unsigned long addr, unsigned long value)
 	*ptr = value;
 }
 
+/**
+ * Read a value from memory.
+ *
+ * @param addr The memory address to read from.
+ * @return The value read from the specified memory address.
+ */
 static unsigned long read_phys(unsigned long addr)
 {
 	volatile unsigned long *ptr;
@@ -38,71 +49,89 @@ static unsigned long read_phys(unsigned long addr)
 	return *ptr;
 }
 
+/**
+ * Fill the specified RAM area.
+ *
+ * The data which is written into RAM is the address of each memory location.
+ * E.g., we write a value of 0x1234 into address 0x1234, we write 0x1235 into
+ * memory address 0x1235, and so on.
+ *
+ * @param start The beginning of the RAM area.
+ * @param stop The end of the RAM area.
+ */
 static void ram_fill(unsigned long start, unsigned long stop)
 {
 	unsigned long addr;
-	/* 
+
-	 * Fill.
-	 */
 	printk(BIOS_DEBUG, "DRAM fill: %lx-%lx\n", start, stop);
-	for(addr = start; addr < stop ; addr += 4) {
+	for (addr = start; addr < stop; addr += 4) {
-		/* Display address being filled */
+		/* Display address being filled. */
-		if (!(addr & 0xffff)) {
+		if (!(addr & 0xffff))
 			printk(BIOS_DEBUG, "%lx\r", addr);
-		}
 		write_phys(addr, addr);
 	};
-	/* Display final address */
+	/* Display final address. */
-	printk(BIOS_DEBUG, "%lx\nDRAM filled\n", addr);
+	printk(BIOS_DEBUG, "%lx\nDRAM filled.\n", addr);
 }
 
+/**
+ * Verify the specified RAM area.
+ *
+ * This checks whether the specified RAM locations return the "correct" data
+ * as written by ram_fill(). The value at address 0x1234 for example should
+ * be 0x1234, the value of address 0x1235 should be 0x1235, and so on.
+ *
+ * @param start The beginning of the RAM area.
+ * @param stop The end of the RAM area.
+ */
 static void ram_verify(unsigned long start, unsigned long stop)
 {
-	unsigned long addr;
+	unsigned long addr, value;
 	int i = 0;
-	/* 
+
-	 * Verify.
-	 */
 	printk(BIOS_DEBUG, "DRAM verify: %lx-%lx\n", start, stop);
-	for(addr = start; addr < stop ; addr += 4) {
+	for (addr = start; addr < stop; addr += 4) {
-		unsigned long value;
+		/* Display address being tested. */
-		/* Display address being tested */
+		if (!(addr & 0xffff))
-		if (!(addr & 0xffff)) {
 			printk(BIOS_DEBUG, "%lx\r", addr);
-		}
 		value = read_phys(addr);
 		if (value != addr) {
-			/* Display address with error */
+			/* Display address with error. */
-			printk(BIOS_ERR, "Fail @%lx Read value=%lx\n", 
+			printk(BIOS_ERR, "Fail @%lx Read value=%lx\n",
-				addr, value);
+			       addr, value);
 			i++;
-			if(i>256) {
+			/* Abort after 256 verify errors. */
+			if (i > 256) {
 				printk(BIOS_ERR, "Aborting.\n");
 				break;
 			}
 		}
 	}
-	/* Display final address */
+
+	/* Display final address. */
 	printk(BIOS_DEBUG, "%lx\r", addr);
+
 	if (i) {
 		printk(BIOS_DEBUG, "\nDRAM did _NOT_ verify!\n");
-	}
+	} else {
-	else {
 		printk(BIOS_DEBUG, "\nDRAM range verified.\n");
 	}
 }
 
-
+/**
+ * Check whether the specified RAM area verifies correctly, and thus whether
+ * we can be reasonably confident that our DRAM setup is correct.
+ *
+ * This is much more of a "Is my DRAM properly configured?" test than
+ * a "Is my DRAM faulty?" test, though.
+ *
+ * @param start The beginning of the RAM area.
+ * @param stop The end of the RAM area.
+ */
 void ram_check(unsigned long start, unsigned long stop)
 {
-	/*
-	 * This is much more of a "Is my DRAM properly configured?"
-	 * test than a "Is my DRAM faulty?" test.  Not all bits
-	 * are tested.   -Tyson
-	 */
 	printk(BIOS_DEBUG, "Testing DRAM: %lx-%lx\n", start, stop);
 	ram_fill(start, stop);
 	ram_verify(start, stop);
 	printk(BIOS_DEBUG, "Done.\n");
 }
-