Author: uwe Date: Sun Oct 17 21:01:48 2010 New Revision: 5955 URL: https://tracker.coreboot.org/trac/coreboot/changeset/5955
Log: 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
Modified: trunk/src/devices/device.c trunk/src/devices/device_util.c trunk/src/devices/hypertransport.c trunk/src/devices/pci_device.c trunk/src/devices/pci_ops.c trunk/src/devices/pci_rom.c trunk/src/devices/pciexp_device.c trunk/src/devices/pcix_device.c trunk/src/devices/root_device.c trunk/src/devices/smbus_ops.c
Modified: trunk/src/devices/device.c ============================================================================== --- trunk/src/devices/device.c Sat Oct 16 10:45:31 2010 (r5954) +++ trunk/src/devices/device.c Sun Oct 17 21:01:48 2010 (r5955) @@ -46,23 +46,20 @@ /** Linked list of free resources */ struct resource *free_resources = NULL;
+DECLARE_SPIN_LOCK(dev_lock)
/** - * @brief Allocate a new device structure. + * Allocate a new device structure. * - * Allocte a new device structure and attached it to the device tree as a + * Allocte a new device structure and attach it to the device tree as a * child of the parent bus. * - * @param parent parent bus the newly created device attached to. - * @param path path to the device to be created. - * - * @return pointer to the newly created device structure. + * @param parent Parent bus the newly created device should be attached to. + * @param path Path to the device to be created. + * @return Pointer to the newly created device structure. * * @see device_path */ - -DECLARE_SPIN_LOCK(dev_lock) - device_t alloc_dev(struct bus *parent, struct device_path *path) { device_t dev, child; @@ -103,10 +100,11 @@ }
/** - * @brief round a number up to an alignment. - * @param val the starting value - * @param roundup Alignment as a power of two - * @returns rounded up number + * Round a number up to an alignment. + * + * @param val The starting value. + * @param roundup Alignment as a power of two. + * @return Rounded up number. */ static resource_t round(resource_t val, unsigned long pow) { @@ -117,15 +115,17 @@ return val; }
-/** Read the resources on all devices of a given bus. - * @param bus bus to read the resources on. +/** + * Read the resources on all devices of a given bus. + * + * @param bus Bus to read the resources on. */ static void read_resources(struct bus *bus) { struct device *curdev;
- printk(BIOS_SPEW, "%s %s bus %x link: %d\n", dev_path(bus->dev), __func__, - bus->secondary, bus->link_num); + printk(BIOS_SPEW, "%s %s bus %x link: %d\n", dev_path(bus->dev), + __func__, bus->secondary, bus->link_num);
/* Walk through all devices and find which resources they need. */ for (curdev = bus->children; curdev; curdev = curdev->sibling) { @@ -205,7 +205,8 @@ return state.result_dev; }
-/* Compute allocate resources is the guts of the resource allocator. +/** + * Compute allocate resources is the guts of the resource allocator. * * The problem. * - Allocate resource locations for every device. @@ -231,6 +232,11 @@ * a device with a couple of resources, and not need to special case it in * the allocator. Also this allows handling of other types of bridges. * + * @param bus The bus we are traversing. + * @param bridge The bridge resource which must contain the bus' resources. + * @param type_mask This value gets ANDed with the resource type. + * @param type This value must match the result of the AND. + * @return TODO */ static void compute_resources(struct bus *bus, struct resource *bridge, unsigned long type_mask, unsigned long type) @@ -392,8 +398,8 @@ * * @param bus The bus we are traversing. * @param bridge The bridge resource which must contain the bus' resources. - * @param type_mask This value gets anded with the resource type. - * @param type This value must match the result of the and. + * @param type_mask This value gets ANDed with the resource type. + * @param type This value must match the result of the AND. */ static void allocate_resources(struct bus *bus, struct resource *bridge, unsigned long type_mask, unsigned long type) @@ -540,10 +546,11 @@ }
#if CONFIG_PCI_64BIT_PREF_MEM == 1 - #define MEM_MASK (IORESOURCE_PREFETCH | IORESOURCE_MEM) +#define MEM_MASK (IORESOURCE_PREFETCH | IORESOURCE_MEM) #else - #define MEM_MASK (IORESOURCE_MEM) +#define MEM_MASK (IORESOURCE_MEM) #endif + #define IO_MASK (IORESOURCE_IO) #define PREF_TYPE (IORESOURCE_PREFETCH | IORESOURCE_MEM) #define MEM_TYPE (IORESOURCE_MEM) @@ -749,9 +756,7 @@ #endif
/** - * @brief Assign the computed resources to the devices on the bus. - * - * @param bus Pointer to the structure for this bus + * Assign the computed resources to the devices on the bus. * * Use the device specific set_resources method to store the computed * resources to hardware. For bridge devices, the set_resources() method @@ -760,6 +765,8 @@ * Mutual recursion: * assign_resources() -> device_operation::set_resources() * device_operation::set_resources() -> assign_resources() + * + * @param bus Pointer to the structure for this bus. */ void assign_resources(struct bus *bus) { @@ -784,9 +791,7 @@ }
/** - * @brief Enable the resources for devices on a link - * - * @param link the link whose devices' resources are to be enabled + * Enable the resources for devices on a link. * * Enable resources of the device by calling the device specific * enable_resources() method. @@ -795,6 +800,7 @@ * order problem. This is done by calling the parent's enable_resources() * method before its childrens' enable_resources() methods. * + * @param link The link whose devices' resources are to be enabled. */ static void enable_resources(struct bus *link) { @@ -815,14 +821,10 @@ }
/** - * @brief Reset all of the devices a bus - * * Reset all of the devices on a bus and clear the bus's reset_needed flag. * - * @param bus pointer to the bus structure - * + * @param bus Pointer to the bus structure. * @return 1 if the bus was successfully reset, 0 otherwise. - * */ int reset_bus(struct bus *bus) { @@ -835,7 +837,7 @@ }
/** - * @brief Scan for devices on a bus. + * Scan for devices on a bus. * * If there are bridges on the bus, recursively scan the buses behind the * bridges. If the setting up and tuning of the bus causes a reset to be @@ -873,7 +875,7 @@ }
/** - * @brief Determine the existence of devices and extend the device tree. + * Determine the existence of devices and extend the device tree. * * Most of the devices in the system are listed in the mainboard Config.lb * file. The device structures for these devices are generated at compile @@ -916,7 +918,7 @@ }
/** - * @brief Configure devices on the devices tree. + * Configure devices on the devices tree. * * Starting at the root of the device tree, travel it recursively in two * passes. In the first pass, we compute and allocate resources (ranges) @@ -1032,7 +1034,7 @@ }
/** - * @brief Enable devices on the device tree. + * Enable devices on the device tree. * * Starting at the root, walk the tree and enable all devices/bridges by * calling the device's enable_resources() method. @@ -1051,14 +1053,13 @@ }
/** - * @brief Initialize a specific device - * - * @param dev the device to be initialized + * Initialize a specific device. * * The parent should be initialized first to avoid having an ordering * problem. This is done by calling the parent's init() * method before its childrens' init() methods. * + * @param dev The device to be initialized. */ static void init_dev(struct device *dev) { @@ -1095,10 +1096,10 @@ }
/** - * @brief Initialize all devices in the global device tree. + * Initialize all devices in the global device tree. * - * Starting at the root device, call the device's init() method to do device- - * specific setup, then call each child's init() method. + * Starting at the root device, call the device's init() method to do + * device-specific setup, then call each child's init() method. */ void dev_initialize(void) {
Modified: trunk/src/devices/device_util.c ============================================================================== --- trunk/src/devices/device_util.c Sat Oct 16 10:45:31 2010 (r5954) +++ trunk/src/devices/device_util.c Sun Oct 17 21:01:48 2010 (r5955) @@ -30,12 +30,12 @@ #include <string.h>
/** - * @brief See if a device structure exists for path + * See if a device structure exists for path. * - * @param bus The bus to find the device on - * @param path The relative path from the bus to the appropriate device - * @return pointer to a device structure for the device on bus at path - * or 0/NULL if no device is found + * @param parent The bus to find the device on. + * @param path The relative path from the bus to the appropriate device. + * @return Pointer to a device structure for the device on bus at path + * or 0/NULL if no device is found. */ device_t find_dev_path(struct bus *parent, struct device_path *path) { @@ -49,11 +49,11 @@ }
/** - * @brief See if a device structure already exists and if not allocate it + * See if a device structure already exists and if not allocate it. * - * @param bus The bus to find the device on - * @param path The relative path from the bus to the appropriate device - * @return pointer to a device structure for the device on bus at path + * @param parent The bus to find the device on. + * @param path The relative path from the bus to the appropriate device. + * @return Pointer to a device structure for the device on bus at path. */ device_t alloc_find_dev(struct bus *parent, struct device_path *path) { @@ -66,11 +66,11 @@ }
/** - * @brief Given a PCI bus and a devfn number, find the device structure + * Given a PCI bus and a devfn number, find the device structure. * - * @param bus The bus number - * @param devfn a device/function number - * @return pointer to the device structure + * @param bus The bus number. + * @param devfn A device/function number. + * @return Pointer to the device structure (if found), 0 otherwise. */ struct device *dev_find_slot(unsigned int bus, unsigned int devfn) { @@ -89,11 +89,11 @@ }
/** - * @brief Given a smbus bus and a device number, find the device structure + * Given an SMBus bus and a device number, find the device structure. * - * @param bus The bus number - * @param addr a device number - * @return pointer to the device structure + * @param bus The bus number. + * @param addr A device number. + * @return Pointer to the device structure (if found), 0 otherwise. */ struct device *dev_find_slot_on_smbus(unsigned int bus, unsigned int addr) { @@ -111,15 +111,18 @@ return result; }
-/** Find a device of a given vendor and type - * @param vendor Vendor ID (e.g. 0x8086 for Intel) - * @param device Device ID +/** + * Find a device of a given vendor and type. + * + * @param vendor A PCI vendor ID (e.g. 0x8086 for Intel). + * @param device A PCI device ID. * @param from Pointer to the device structure, used as a starting point * in the linked list of all_devices, which can be 0 to start at the - * head of the list (i.e. all_devices) - * @return Pointer to the device struct + * head of the list (i.e. all_devices). + * @return Pointer to the device struct. */ -struct device *dev_find_device(unsigned int vendor, unsigned int device, struct device *from) +struct device *dev_find_device(unsigned int vendor, unsigned int device, + struct device *from) { if (!from) from = all_devices; @@ -131,12 +134,14 @@ return from; }
-/** Find a device of a given class - * @param class Class of the device +/** + * Find a device of a given class. + * + * @param class Class of the device. * @param from Pointer to the device structure, used as a starting point * in the linked list of all_devices, which can be 0 to start at the - * head of the list (i.e. all_devices) - * @return Pointer to the device struct + * head of the list (i.e. all_devices). + * @return Pointer to the device struct. */ struct device *dev_find_class(unsigned int class, struct device *from) { @@ -149,12 +154,14 @@ return from; }
-/* Warning: This function uses a static buffer. Don't call it more than once - * from the same print statement! */ - +/* + * Warning: This function uses a static buffer. Don't call it more than once + * from the same print statement! + */ const char *dev_path(device_t dev) { static char buffer[DEVICE_PATH_MAX]; + buffer[0] = '\0'; if (!dev) { memcpy(buffer, "<null>", 7); @@ -262,6 +269,8 @@
/** * Allocate 64 more resources to the free list. + * + * @return TODO. */ static int allocate_more_resources(void) { @@ -283,8 +292,14 @@
/** * Remove resource res from the device's list and add it to the free list. + * + * @param dev TODO + * @param res TODO + * @param prev TODO + * @return TODO. */ -static void free_resource(device_t dev, struct resource *res, struct resource *prev) +static void free_resource(device_t dev, struct resource *res, + struct resource *prev) { if (prev) prev->next = res->next; @@ -297,7 +312,8 @@ /** * See if we have unused but allocated resource structures. * If so remove the allocation. - * @param dev The device to find the resource on + * + * @param dev The device to find the resource on. */ void compact_resources(device_t dev) { @@ -312,16 +328,17 @@ } }
- /** - * See if a resource structure already exists for a given index - * @param dev The device to find the resource on - * @param index The index of the resource on the device. - * @return the resource if it already exists + * See if a resource structure already exists for a given index. + * + * @param dev The device to find the resource on. + * @param index The index of the resource on the device. + * @return The resource, if it already exists. */ struct resource *probe_resource(device_t dev, unsigned index) { struct resource *res; + /* See if there is a resource with the appropriate index */ for (res = dev->resource_list; res; res = res->next) { if (res->index == index) @@ -331,11 +348,14 @@ }
/** - * See if a resource structure already exists for a given index and if - * not allocate one. Then initialize the initialize the resource - * to default values. - * @param dev The device to find the resource on - * @param index The index of the resource on the device. + * See if a resource structure already exists for a given index and if not + * allocate one. + * + * Then initialize the initialize the resource to default values. + * + * @param dev The device to find the resource on. + * @param index The index of the resource on the device. + * @return TODO. */ struct resource *new_resource(device_t dev, unsigned index) { @@ -378,8 +398,10 @@
/** * Return an existing resource structure for a given index. - * @param dev The device to find the resource on - * @param index The index of the resource on the device. + * + * @param dev The device to find the resource on. + * @param index The index of the resource on the device. + * return TODO. */ struct resource *find_resource(device_t dev, unsigned index) { @@ -397,10 +419,11 @@
/** - * @brief round a number up to the next multiple of gran - * @param val the starting value - * @param gran granularity we are aligning the number to. - * @returns aligned value + * Round a number up to the next multiple of gran. + * + * @param val The starting value. + * @param gran Granularity we are aligning the number to. + * @return The aligned value. */ static resource_t align_up(resource_t val, unsigned long gran) { @@ -412,10 +435,11 @@ }
/** - * @brief round a number up to the previous multiple of gran - * @param val the starting value - * @param gran granularity we are aligning the number to. - * @returns aligned value + * Round a number up to the previous multiple of gran. + * + * @param val The starting value. + * @param gran Granularity we are aligning the number to. + * @return The aligned value. */ static resource_t align_down(resource_t val, unsigned long gran) { @@ -426,9 +450,10 @@ }
/** - * @brief Compute the maximum address that is part of a resource - * @param resource the resource whose limit is desired - * @returns the end + * Compute the maximum address that is part of a resource. + * + * @param resource The resource whose limit is desired. + * @return The end. */ resource_t resource_end(struct resource *resource) { @@ -449,9 +474,10 @@ }
/** - * @brief Compute the maximum legal value for resource->base - * @param resource the resource whose maximum is desired - * @returns the maximum + * Compute the maximum legal value for resource->base. + * + * @param resource The resource whose maximum is desired. + * @return The maximum. */ resource_t resource_max(struct resource *resource) { @@ -463,8 +489,10 @@ }
/** - * @brief return the resource type of a resource - * @param resource the resource type to decode. + * Return the resource type of a resource. + * + * @param resource The resource type to decode. + * @return TODO. */ const char *resource_type(struct resource *resource) { @@ -482,11 +510,14 @@ }
/** - * @brief print the resource that was just stored. - * @param dev the device the stored resorce lives on - * @param resource the resource that was just stored. + * Print the resource that was just stored. + * + * @param dev The device the stored resorce lives on. + * @param resource The resource that was just stored. + * @param comment TODO */ -void report_resource_stored(device_t dev, struct resource *resource, const char *comment) +void report_resource_stored(device_t dev, struct resource *resource, + const char *comment) { if (resource->flags & IORESOURCE_STORED) { char buf[10];
Modified: trunk/src/devices/hypertransport.c ============================================================================== --- trunk/src/devices/hypertransport.c Sat Oct 16 10:45:31 2010 (r5954) +++ trunk/src/devices/hypertransport.c Sun Oct 17 21:01:48 2010 (r5955) @@ -23,10 +23,6 @@ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
-/* - 2005.11 yhlu add let the real sb to use small uintid -*/ - #include <bitops.h> #include <console/console.h> #include <device/device.h> @@ -35,8 +31,9 @@ #include <device/pci_ids.h> #include <device/hypertransport.h>
-/* The hypertransport link is already optimized in pre-ram code - * so don't do it again +/* + * The hypertransport link is already optimized in pre-RAM code so don't do + * it again. */ #define OPT_HT_LINK 0
@@ -261,7 +258,6 @@ }
return reset_needed; - }
static unsigned ht_lookup_slave_capability(struct device *dev) @@ -598,17 +594,18 @@ }
/** - * @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. * * This function is the default scan_bus() method for PCI bridge devices. * - * @param dev pointer to the bridge device - * @param max the highest bus number assgined up to now - * - * @return The maximum bus number found, after scanning all subordinate busses + * @param bus TODO + * @param min_devfn TODO + * @param max_devfn TODO + * @param max The highest bus number assgined up to now. + * @return The maximum bus number found, after scanning all subordinate busses. */ static unsigned int hypertransport_scan_chain_x(struct bus *bus, unsigned min_devfn, unsigned max_devfn, unsigned int max) @@ -623,7 +620,6 @@ return do_pci_scan_bridge(dev, max, hypertransport_scan_chain_x); }
- /** Default device operations for hypertransport bridges */ static struct pci_operations ht_bus_ops_pci = { .set_subsystem = 0,
Modified: trunk/src/devices/pci_device.c ============================================================================== --- trunk/src/devices/pci_device.c Sat Oct 16 10:45:31 2010 (r5954) +++ trunk/src/devices/pci_device.c Sun Oct 17 21:01:48 2010 (r5955) @@ -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])
Modified: trunk/src/devices/pci_ops.c ============================================================================== --- trunk/src/devices/pci_ops.c Sat Oct 16 10:45:31 2010 (r5954) +++ trunk/src/devices/pci_ops.c Sun Oct 17 21:01:48 2010 (r5955) @@ -25,7 +25,8 @@ #include <device/pci_ids.h> #include <device/pci_ops.h>
-/* The only consumer of the return value of get_pbus() is ops_pci_bus(). +/* + * The only consumer of the return value of get_pbus() is ops_pci_bus(). * ops_pci_bus() can handle being passed NULL and auto-picks working ops. */ static struct bus *get_pbus(device_t dev)
Modified: trunk/src/devices/pci_rom.c ============================================================================== --- trunk/src/devices/pci_rom.c Sat Oct 16 10:45:31 2010 (r5954) +++ trunk/src/devices/pci_rom.c Sun Oct 17 21:01:48 2010 (r5955) @@ -29,7 +29,7 @@ #include <string.h> #include <cbfs.h>
-struct rom_header * pci_rom_probe(struct device *dev) +struct rom_header *pci_rom_probe(struct device *dev) { struct rom_header *rom_header; struct pci_data *rom_data;
Modified: trunk/src/devices/pciexp_device.c ============================================================================== --- trunk/src/devices/pciexp_device.c Sat Oct 16 10:45:31 2010 (r5954) +++ trunk/src/devices/pciexp_device.c Sun Oct 17 21:01:48 2010 (r5955) @@ -24,7 +24,6 @@ #include <device/pci_ids.h> #include <device/pciexp.h>
- static void pciexp_tune_dev(device_t dev) { unsigned cap; @@ -63,7 +62,6 @@ return max; }
- unsigned int pciexp_scan_bridge(device_t dev, unsigned int max) { return do_pci_scan_bridge(dev, max, pciexp_scan_bus);
Modified: trunk/src/devices/pcix_device.c ============================================================================== --- trunk/src/devices/pcix_device.c Sat Oct 16 10:45:31 2010 (r5954) +++ trunk/src/devices/pcix_device.c Sun Oct 17 21:01:48 2010 (r5955) @@ -24,7 +24,6 @@ #include <device/pci_ids.h> #include <device/pcix.h>
- static void pcix_tune_dev(device_t dev) { unsigned cap; @@ -130,7 +129,6 @@ return max; }
- /** Default device operations for PCI-X bridges */ static struct pci_operations pcix_bus_ops_pci = { .set_subsystem = 0,
Modified: trunk/src/devices/root_device.c ============================================================================== --- trunk/src/devices/root_device.c Sat Oct 16 10:45:31 2010 (r5954) +++ trunk/src/devices/root_device.c Sun Oct 17 21:01:48 2010 (r5955) @@ -28,9 +28,10 @@ #include <reset.h>
/** - * Read the resources for the root device, - * that encompass the resources for the entire system. - * @param root Pointer to the device structure for the system root device + * Read the resources for the root device, that encompass the resources for + * the entire system. + * + * @param root Pointer to the device structure for the system root device. */ static void root_dev_read_resources(device_t root) { @@ -38,11 +39,12 @@ }
/** - * @brief Write the resources for every device + * Write the resources for every device. + * + * Write the resources for the root device, and every device under it which + * are all of the devices. * - * Write the resources for the root device, - * and every device under it which are all of the devices. - * @param root Pointer to the device structure for the system root device + * @param root Pointer to the device structure for the system root device. */ static void root_dev_set_resources(device_t root) { @@ -50,7 +52,7 @@ }
/** - * @brief Scan devices on static buses. + * Scan devices on static buses. * * The enumeration of certain buses is purely static. The existence of * devices on those buses can be completely determined at compile time @@ -67,8 +69,8 @@ * This function is the default scan_bus() method for the root device and * LPC bridges. * - * @param bus Pointer to the device structure which the static buses are attached - * @param max Maximum bus number currently used before scanning. + * @param bus Pointer to the device to which the static buses are attached to. + * @param max Maximum bus number currently used before scanning. * @return Largest bus number used. */ static int smbus_max = 0; @@ -120,12 +122,13 @@ }
/** - * @brief Scan root bus for generic systems - * - * @param root The root device structure - * @param max The current bus number scanned so far, usually 0x00 + * Scan root bus for generic systems. * * This function is the default scan_bus() method of the root device. + * + * @param root The root device structure. + * @param max The current bus number scanned so far, usually 0x00. + * @return TODO. */ static unsigned int root_dev_scan_bus(device_t root, unsigned int max) { @@ -143,10 +146,10 @@ }
/** - * @brief Default device operation for root device + * Default device operation for root device. * * This is the default device operation for root devices. These operations - * should be fully usable as is. However the chip_operations::enable_dev() + * should be fully usable as is. However the chip_operations::enable_dev() * of a motherboard can override this if you want non-default behavior. */ struct device_operations default_dev_ops_root = {
Modified: trunk/src/devices/smbus_ops.c ============================================================================== --- trunk/src/devices/smbus_ops.c Sat Oct 16 10:45:31 2010 (r5954) +++ trunk/src/devices/smbus_ops.c Sun Oct 17 21:01:48 2010 (r5955) @@ -38,11 +38,15 @@ return pbus; }
-/*multi level i2c MUX??? may need to find the first i2c device and then set link - * down to current dev - 1 store get_pbus_smbus list link - 2 reverse the link and call set link */ - +/* + * Multi-level I2C MUX? may need to find the first i2c device and then set link + * down to current dev. + * + * 1 store get_pbus_smbus list link + * 2 reverse the link and call set link. + * + * @param dev TODO. + */ int smbus_set_link(device_t dev) { struct bus *pbus_a[4]; // 4 level mux only. Enough? @@ -110,5 +114,3 @@ { return ops_smbus_bus(get_pbus_smbus(dev))->block_write(dev, cmd, bytes, buffer); } - -