Various Doxygen comment fixes, typo fixes, etc.
- Fix incorrect argument names for @param entries.
- Add missing @param and @return entries, partly as TODOs.
- s/@returns/@return/, that's a typo.
- Small whitespace fixes while I'm at it.
- Drop useless @brief commands, they just clutter the comments and make them
harder to read. Doxygen has an option to always use the first sentence
of a Doxygen-comment as @brief automatically (should be on per default).
Signed-off-by: Uwe Hermann <uwe@hermann-uwe.de>
Acked-by: Uwe Hermann <uwe@hermann-uwe.de>
git-svn-id: svn://svn.coreboot.org/coreboot/trunk@5955 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1
diff --git a/src/devices/pci_device.c b/src/devices/pci_device.c
index 16e8d3f..ac799c5 100644
--- a/src/devices/pci_device.c
+++ b/src/devices/pci_device.c
@@ -106,8 +106,9 @@
* matching capability. Always start at the head of the list.
*
* @param dev Pointer to the device structure.
- * @param cap_type PCI_CAP_LIST_ID of the PCI capability we're looking for.
+ * @param cap PCI_CAP_LIST_ID of the PCI capability we're looking for.
* @param last Location of the PCI capability register to start from.
+ * @return The next matching capability.
*/
unsigned pci_find_next_capability(struct device *dev, unsigned cap,
unsigned last)
@@ -157,7 +158,8 @@
* capability. Always start at the head of the list.
*
* @param dev Pointer to the device structure.
- * @param cap_type PCI_CAP_LIST_ID of the PCI capability we're looking for.
+ * @param cap PCI_CAP_LIST_ID of the PCI capability we're looking for.
+ * @return The next matching capability.
*/
unsigned pci_find_capability(device_t dev, unsigned cap)
{
@@ -169,6 +171,7 @@
*
* @param dev Pointer to the device structure.
* @param index Address of the PCI configuration register.
+ * @return TODO
*/
struct resource *pci_get_resource(struct device *dev, unsigned long index)
{
@@ -373,11 +376,11 @@
/* See if the bridge I/O resources are implemented. */
moving_base = ((u32) pci_moving_config8(dev, PCI_IO_BASE)) << 8;
moving_base |=
- ((u32) pci_moving_config16(dev, PCI_IO_BASE_UPPER16)) << 16;
+ ((u32) pci_moving_config16(dev, PCI_IO_BASE_UPPER16)) << 16;
moving_limit = ((u32) pci_moving_config8(dev, PCI_IO_LIMIT)) << 8;
moving_limit |=
- ((u32) pci_moving_config16(dev, PCI_IO_LIMIT_UPPER16)) << 16;
+ ((u32) pci_moving_config16(dev, PCI_IO_LIMIT_UPPER16)) << 16;
moving = moving_base & moving_limit;
@@ -386,17 +389,14 @@
/* See if the bridge prefmem resources are implemented. */
moving_base =
- ((resource_t) pci_moving_config16(dev, PCI_PREF_MEMORY_BASE)) << 16;
+ ((resource_t) pci_moving_config16(dev, PCI_PREF_MEMORY_BASE)) << 16;
moving_base |=
- ((resource_t) pci_moving_config32(dev, PCI_PREF_BASE_UPPER32)) <<
- 32;
+ ((resource_t) pci_moving_config32(dev, PCI_PREF_BASE_UPPER32)) << 32;
moving_limit =
- ((resource_t) pci_moving_config16(dev, PCI_PREF_MEMORY_LIMIT)) <<
- 16;
+ ((resource_t) pci_moving_config16(dev, PCI_PREF_MEMORY_LIMIT)) << 16;
moving_limit |=
- ((resource_t) pci_moving_config32(dev, PCI_PREF_LIMIT_UPPER32)) <<
- 32;
+ ((resource_t) pci_moving_config32(dev, PCI_PREF_LIMIT_UPPER32)) << 32;
moving = moving_base & moving_limit;
/* Initialize the prefetchable memory constraints on the current bus. */
@@ -704,7 +704,7 @@
};
/**
- * @brief Detect the type of downstream bridge
+ * Detect the type of downstream bridge.
*
* This function is a heuristic to detect which type of bus is downstream
* of a PCI-to-PCI bridge. This functions by looking for various capability
@@ -768,8 +768,10 @@
}
/**
- * Set up PCI device operation. Check if it already has a driver. If not, use
- * find_device_operations, or set to a default based on type.
+ * Set up PCI device operation.
+ *
+ * Check if it already has a driver. If not, use find_device_operations(),
+ * or set to a default based on type.
*
* @param dev Pointer to the device whose pci_ops you want to set.
* @see pci_drivers
@@ -827,7 +829,7 @@
}
/**
- * @brief See if we have already allocated a device structure for a given devfn.
+ * See if we have already allocated a device structure for a given devfn.
*
* Given a linked list of PCI device structures and a devfn number, find the
* device structure correspond to the devfn, if present. This function also
@@ -835,7 +837,6 @@
*
* @param list The device structure list.
* @param devfn A device/function number.
- *
* @return Pointer to the device structure found or NULL if we have not
* allocated a device for this devfn yet.
*/
@@ -881,18 +882,17 @@
}
/**
- * @brief Scan a PCI bus.
+ * Scan a PCI bus.
*
* Determine the existence of a given PCI device. Allocate a new struct device
* if dev==NULL was passed in and the device exists in hardware.
*
- * @param bus pointer to the bus structure
- * @param devfn to look at
- *
- * @return The device structure for hte device (if found)
- * or the NULL if no device is found.
+ * @param dev Pointer to the dev structure.
+ * @param bus Pointer to the bus structure.
+ * @param devfn A device/function number to look at.
+ * @return The device structure for the device (if found), NULL otherwise.
*/
-device_t pci_probe_dev(device_t dev, struct bus * bus, unsigned devfn)
+device_t pci_probe_dev(device_t dev, struct bus *bus, unsigned devfn)
{
u32 id, class;
u8 hdr_type;
@@ -989,7 +989,7 @@
}
/**
- * @brief Scan a PCI bus.
+ * Scan a PCI bus.
*
* Determine the existence of devices and bridges on a PCI bus. If there are
* bridges on the bus, recursively scan the buses behind the bridges.
@@ -997,12 +997,11 @@
* This function is the default scan_bus() method for the root device
* 'dev_root'.
*
- * @param bus pointer to the bus structure
- * @param min_devfn minimum devfn to look at in the scan usually 0x00
- * @param max_devfn maximum devfn to look at in the scan usually 0xff
- * @param max current bus number
- *
- * @return The maximum bus number found, after scanning all subordinate busses
+ * @param bus Pointer to the bus structure.
+ * @param min_devfn Minimum devfn to look at in the scan, usually 0x00.
+ * @param max_devfn Maximum devfn to look at in the scan, usually 0xff.
+ * @param max Current bus number.
+ * @return The maximum bus number found, after scanning all subordinate busses.
*/
unsigned int pci_scan_bus(struct bus *bus,
unsigned min_devfn, unsigned max_devfn,
@@ -1084,7 +1083,7 @@
}
/**
- * @brief Scan a PCI bridge and the buses behind the bridge.
+ * Scan a PCI bridge and the buses behind the bridge.
*
* Determine the existence of buses behind the bridge. Set up the bridge
* according to the result of the scan.
@@ -1093,6 +1092,7 @@
*
* @param dev Pointer to the bridge device.
* @param max The highest bus number assigned up to now.
+ * @param do_scan_bus TODO
* @return The maximum bus number found, after scanning all subordinate buses.
*/
unsigned int do_pci_scan_bridge(struct device *dev, unsigned int max,
@@ -1164,7 +1164,7 @@
}
/**
- * @brief Scan a PCI bridge and the buses behind the bridge.
+ * Scan a PCI bridge and the buses behind the bridge.
*
* Determine the existence of buses behind the bridge. Set up the bridge
* according to the result of the scan.
@@ -1181,14 +1181,13 @@
}
/**
- * @brief Scan a PCI domain.
+ * Scan a PCI domain.
*
* This function is the default scan_bus() method for PCI domains.
*
- * @param dev pointer to the domain
- * @param max the highest bus number assgined up to now
- *
- * @return The maximum bus number found, after scanning all subordinate busses
+ * @param dev Pointer to the domain.
+ * @param max The highest bus number assigned up to now.
+ * @return The maximum bus number found, after scanning all subordinate busses.
*/
unsigned int pci_domain_scan_bus(device_t dev, unsigned int max)
{
@@ -1198,8 +1197,7 @@
#if CONFIG_PC80_SYSTEM == 1
/**
- *
- * @brief Assign IRQ numbers
+ * Assign IRQ numbers.
*
* This function assigns IRQs for all functions contained within the indicated
* device address. If the device does not exist or does not require interrupts
@@ -1207,12 +1205,11 @@
*
* This function should be called for each PCI slot in your system.
*
- * @param bus
- * @param slot
- * @param pIntAtoD is an array of IRQ #s that are assigned to PINTA through
- * PINTD of this slot. The particular irq #s that are passed in
- * depend on the routing inside your southbridge and on your
- * motherboard.
+ * @param bus Pointer to the bus structure.
+ * @param slot TODO
+ * @param pIntAtoD An array of IRQ #s that are assigned to PINTA through PINTD
+ * of this slot. The particular IRQ #s that are passed in depend on the
+ * routing inside your southbridge and on your board.
*/
void pci_assign_irqs(unsigned bus, unsigned slot,
const unsigned char pIntAtoD[4])