code refromat, doxidization

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

2 files changed, 34 insertions, 8 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,