code refromat, doxidization

git-svn-id: svn://svn.coreboot.org/coreboot/trunk@1547 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1

3 files changed, 52 insertions, 9 deletions

diff --git a/src/devices/pci_device.c b/src/devices/pci_device.c
index 4a248224cb..ec48e7f852 100644
--- a/src/devices/pci_device.c
+++ b/src/devices/pci_device.c
@@ -562,7 +562,7 @@ unsigned int pci_scan_bus(struct bus *bus, unsigned min_devfn,
 
 	post_code(0x24);
 
-	/* probe all devices on this bus with some optimization for
+	/* probe all devices/functions on this bus with some optimization for
 	 * non-existence and single funcion devices */
 	for (devfn = min_devfn; devfn <= max_devfn; devfn++) {
 		uint32_t id, class;
@@ -602,13 +602,15 @@ unsigned int pci_scan_bus(struct bus *bus, unsigned min_devfn,
 			 * device */
 			/* FIXME: What happen if this PCI device listed as
 			 * static device but does not exist ? This calls
-			 * some arbitray code without any justification */
+			 * some arbitray code without any justification
+			 * Also, it calls the enable function regardlessly
+			 * the value of dev->enabled  */
 			if (dev->chip && dev->chip->control &&
 			    dev->chip->control->enable_dev) {
-				int enable  = dev->enabled;
+				int enabled  = dev->enabled;
 				dev->enabled = 1;
 				dev->chip->control->enable_dev(dev);
-				dev->enabled = enable;
+				dev->enabled = enabled;
 			}
 			/* Now read the vendor and device id */
 			id = pci_read_config32(dev, PCI_VENDOR_ID);
@@ -616,7 +618,7 @@ unsigned int pci_scan_bus(struct bus *bus, unsigned min_devfn,
 		/* Read the rest of the pci configuration information */
 		hdr_type = pci_read_config8(dev, PCI_HEADER_TYPE);
 		class = pci_read_config32(dev, PCI_CLASS_REVISION);
-		
+
 		/* Store the interesting information in the device structure */
 		dev->vendor = id & 0xffff;
 		dev->device = (id >> 16) & 0xffff;
@@ -640,8 +642,8 @@ unsigned int pci_scan_bus(struct bus *bus, unsigned min_devfn,
 		/* Now run the magic enable/disable sequence for the device */
 		if (dev->ops && dev->ops->enable) {
 			dev->ops->enable(dev);
-		}
-		else if (dev->chip && dev->chip->control && dev->chip->control->enable_dev) {
+		} else if (dev->chip && dev->chip->control &&
+			   dev->chip->control->enable_dev) {
 			dev->chip->control->enable_dev(dev);
 		}
 
diff --git a/src/devices/root_device.c b/src/devices/root_device.c
index c2173d3947..78a81608ad 100644
--- a/src/devices/root_device.c
+++ b/src/devices/root_device.c
@@ -4,7 +4,7 @@
 
 /** 
  * Read the resources for the root device,
- * that encompase the resources for the entire system.
+ * that encompass the resources for the entire system.
  * @param root Pointer to the device structure for the system root device
  */
 void root_dev_read_resources(device_t root)
@@ -92,6 +92,13 @@ unsigned int walk_static_devices(device_t bus, unsigned int max)
 	return max;
 }
 
+/**
+ * @brief Enable resources for children devices
+ *
+ * @param dev the device whos childrens resources are to be enabled
+ *
+ * This function is call by the enable_resource 
+ */
 void enable_childrens_resources(device_t dev)
 {
 	unsigned link;
@@ -103,11 +110,28 @@ void enable_childrens_resources(device_t dev)
 	}
 }
 
+/**
+ * @brief Scan root bus for generic PCI systems
+ *
+ * @param root the root device structure
+ * @param max the current bus number scanned so fat, usually 0x00
+ *
+ */
 unsigned int root_dev_scan_pci_bus(device_t root, unsigned int max)
 {
 	return pci_scan_bus(&root->link[0], 0, 0xff, max);
 }
 
+/**
+ * @brief Default device operation for root device
+ *
+ * This is the default device operation for root devices in PCI based systems.
+ * The static enumeration code chip_control::enumerate() of mainboards usually
+ * override this operation with their own device operations. An notable example
+ * is mainboard operations for AMD K8 mainboards. They replace the scan_bus()
+ * method with amdk8_scan_root_bus() due to the special device layout of AMD K8
+ * systems.
+ */
 struct device_operations default_dev_ops_root = {
 	.read_resources   = root_dev_read_resources,
 	.set_resources    = root_dev_set_resources,
diff --git a/src/northbridge/amd/amdk8/northbridge.c b/src/northbridge/amd/amdk8/northbridge.c
index 867654cdf5..8a252d0054 100644
--- a/src/northbridge/amd/amdk8/northbridge.c
+++ b/src/northbridge/amd/amdk8/northbridge.c
@@ -485,6 +485,24 @@ static void amdk8_set_resources(device_t dev)
 	}
 }
 
+/**
+ * @brief Scan root bus for AMD K8 systems
+ *
+ * @param root the root device structure
+ * @max the current bus number scanned so far, usually 0x00
+ *
+ * The root device in a AMD K8 system is not at Bus 0, Device 0, Fun 0
+ * as other PCI based systems. The northbridge is at Bus 0, Device 0x18,
+ * Fun 0. We have to call the pci_scan_bus() with PCI_DEVFN(0x18,0) as
+ * the starting device instead of PCI_DEVFN(0x0, 0) as in the default
+ * root_dev_scan_pci_bus().
+ *
+ * This function is set up as the default scan_bus() method for mainboards'
+ * device_operations for AMD K8 mainboards in mainboard.c
+ *
+ * @see device_operation()
+ * @see root_dev_scan_pci_bus()
+ */
 unsigned int amdk8_scan_root_bus(device_t root, unsigned int max)
 {
 	unsigned reg;
@@ -492,7 +510,6 @@ unsigned int amdk8_scan_root_bus(device_t root, unsigned int max)
 	printk_debug("amdk8_scan_root_bus\n");
 
 	/* Unmap all of the HT chains */
-	printk_debug("amdk8_scan_root_bus: clearing HT registers\n");
 	for (reg = 0xe0; reg <= 0xec; reg += 4) {
 		f1_write_config32(reg, 0);
 	}