Doxidization, reformat

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

1 files changed, 86 insertions, 17 deletions

diff --git a/src/devices/chip.c b/src/devices/chip.c
index d8a59e3062..33f3976eb8 100644
--- a/src/devices/chip.c
+++ b/src/devices/chip.c
@@ -9,8 +9,22 @@
 #include <device/chip.h>
 #include <device/pci.h>
 
-void
-chip_configure(struct chip *root, enum chip_pass pass)
+/**
+ * @brief Configure static devices
+ *
+ * Starting from the static device 'root', walk the tree and configure each
+ * device by calling the device specific chip_control::enable().
+ *
+ * This function is only an iterator, the exact definition of 'configure'
+ * depends on the device specific implementation of chip_control::enable(). 
+ *
+ * @param root root of the static device tree to be configured.
+ * @param pass pass of the configuration operation to be perfromed.
+ *
+ * @see chip_pass
+ * @see chip_control::enable
+ */  
+void chip_configure(struct chip *root, enum chip_pass pass)
 {
 	struct chip *c;
 
@@ -25,24 +39,37 @@ chip_configure(struct chip *root, enum chip_pass pass)
 	}
 }
 
-/** Convert a static struct chip structure to a set of dynamic device structures.
- * @param chip Static chip structure to start with.
+/**
+ * @brief Convert static device structures to dynamic structures.
+ *
+ * A static device may contain one or more dynamic devices. Dynamic device
+ * structures of these devices have to be generated before the enumeration
+ * of dynamic devices. This function converts a static chip structure to a
+ * set of dynamic device structures.
+ *
+ * This function is the generic method called by enumerate_static_device_chain()
+ * for static devices. Devices extend this default behavior by defining their
+ * own chip_controll::enumerate(). Generally, device specific
+ * chip_control::enumerate() method calls this function as its last operation.
+ *
+ * @param chip static chip structure to be converted.
+ *
  */
-
 void chip_enumerate(struct chip *chip)
 {
 	struct chip *child;
 	device_t dev;
 	int link;
 	int i;
+
 	dev = 0;
 	link = 0;
-#if 1
+
 	if (chip->control && chip->control->name) {
 		printk_debug("Enumerating: %s\n", chip->control->name);
 	}
-#endif
-	for(i = 0; i < MAX_CHIP_PATHS; i++) {
+
+	for (i = 0; i < MAX_CHIP_PATHS; i++) {
 		int identical_paths;
 		identical_paths = 
 			(i > 0) &&
@@ -55,6 +82,7 @@ void chip_enumerate(struct chip *chip)
 			parent = chip->bus;
 			switch(chip->path[i].path.type) {
 			case DEVICE_PATH_NONE:
+				/* no dynamic device associated */
 				break;
 			case DEVICE_PATH_PCI:
 				bus = chip->path[i].path.u.pci.bus;
@@ -62,7 +90,7 @@ void chip_enumerate(struct chip *chip)
 					device_t dev;
 					int i = 1;
 					dev = chip->dev;
-					while(dev && (i != bus)) {
+					while (dev && (i != bus)) {
 						dev = dev->next;
 						i++;
 					}
@@ -75,18 +103,21 @@ void chip_enumerate(struct chip *chip)
 				dev = alloc_dev(parent, &chip->path[i].path);
 				break;
 			}
-		}
-		else {
+		} else {
 			link += 1;
 		}
+
 		if (dev) {
 			struct chip_resource *res, *res_limit;
-			printk_spew("path (%p) %s %s", dev, dev_path(dev), identical_paths?"identical":"");
-			printk_spew(" parent: (%p) %s\n",dev->bus->dev,  dev_path(dev->bus->dev));
+			printk_spew("path (%p) %s %s",
+				    dev, dev_path(dev),
+				    identical_paths?"identical":"");
+			printk_spew(" parent: (%p) %s\n",
+				    dev->bus->dev,  dev_path(dev->bus->dev));
 			dev->chip = chip;
 			dev->enable = chip->path[i].enable;
 			dev->links = link + 1;
-			for(child = chip->children; child; child = child->next) {
+			for (child = chip->children; child; child = child->next) {
 				if (!child->bus && child->link == i) {
 					child->bus = &dev->link[link];
 				}
@@ -102,21 +133,42 @@ void chip_enumerate(struct chip *chip)
 				}
 			}
 		}
+
 		if (dev && !chip->dev) {
 			chip->dev = dev;
 		}
 	}
-	for(child = chip->children; child; child = child->next) {
+
+	for (child = chip->children; child; child = child->next) {
 		if (!child->bus) {
 			child->bus = &chip->dev->link[0];
 		}
 	}
 }
 
+/**
+ * @brief Enumerate a static device tree.
+ *
+ * A static device chain is a linked list of static device structures which are
+ * on the same branch of the static device tree. This function does not only
+ * enumerate the devices on a single chain, as its name suggest, it also walks
+ * into the subordinary chains. It calls the device specific
+ * chip_control::enumerate() of the device if one exists or calls the generic
+ * chip_enumerate(). 
+ *
+ * This function is only an iterator, the exact definition of 'enumerate'
+ * depends on the implementation of the generic chip_enumerate() and/or device
+ * specific chip_control::enumerate(). 
+ *
+ * @param root static chip structure to start with.
+ *
+ * @see chip_control::enumerate()
+ */
 static void enumerate_static_device_chain(struct chip *root)
 {
 	struct chip *chip;
-	for(chip = root; chip; chip = chip->next) {
+
+	for (chip = root; chip; chip = chip->next) {
 		void (*enumerate)(struct chip *chip);
 		enumerate = chip_enumerate;
 		if (chip->control && chip->control->enumerate) {
@@ -125,13 +177,30 @@ static void enumerate_static_device_chain(struct chip *root)
 		enumerate(chip);
 	}
 
-	for(chip = root; chip; chip = chip->next) {
+	for (chip = root; chip; chip = chip->next) {
 		if (chip->children) {
 			enumerate_static_device_chain(chip->children);
 		}
 	}
 }
 
+/**
+ * @brief Enumerate static devices in the system.
+ *
+ * \note The definition of 'enumerate' is not clear in this context. Does it mean
+ * probe ?
+ *
+ * \note How do we determine the existence of the static devices ? Static
+ * devices are listed in the config file and generated at compile time by config
+ * tool. This function is called at certain point in the early stage of
+ * LinuxBIOS. It uses the chip_enumerate() function to convert the static
+ * structures into dynamic ones. What if the static devices listed in the config
+ * file does actually not exist in the system ? Is there any side effect of
+ * these 'phantom' device structures
+ *
+ * The static device does not necesarry conform to the dynamic device tree in
+ * the system.
+ */
 void enumerate_static_devices(void)
 {
 	enumerate_static_device_chain(&static_root);