From rdunlap@xenotime.net Wed Nov 28 11:54:57 2007 From: Randy Dunlap Date: Wed, 28 Nov 2007 09:04:30 -0800 Subject: pci hotplug: kernel-doc fixes To: pcihpd-discuss@lists.sourceforge.net Cc: scottm@somanetworks.com, kristen.c.accardi@intel.com Message-ID: <20071128090430.b7ac8f2a.rdunlap@xenotime.net> From: Randy Dunlap acpiphp.h: not using kernel-doc, so change /** to /* acpiphp_core.c: lots of kernel-doc cleanups acpiphp_glue.c: lots of kernel-doc cleanups acpiphp_ibm.c: lots of kernel-doc cleanups cpqphp_core.c: lots of kernel-doc cleanups cpqphp_ctrl.c: lots of kernel-doc cleanups fakephp.c: correct kernel-doc notation pciehp_ctrl.c: correct kernel-doc notation rpadlpar_core.c: correct function names & kernel-doc notation rpaphp_core.c: correct kernel-doc notation shpchp_ctrl.c: correct kernel-doc notation Signed-off-by: Randy Dunlap Cc: Kristen Accardi Signed-off-by: Greg Kroah-Hartman --- drivers/pci/hotplug/acpiphp.h | 8 +-- drivers/pci/hotplug/acpiphp_core.c | 29 ++++------ drivers/pci/hotplug/acpiphp_glue.c | 36 +++++-------- drivers/pci/hotplug/acpiphp_ibm.c | 47 +++++++++-------- drivers/pci/hotplug/cpqphp_core.c | 41 ++++++++------- drivers/pci/hotplug/cpqphp_ctrl.c | 96 +++++++++++++++++------------------- drivers/pci/hotplug/fakephp.c | 14 ++--- drivers/pci/hotplug/pciehp_ctrl.c | 16 +++--- drivers/pci/hotplug/rpadlpar_core.c | 19 +++---- drivers/pci/hotplug/rpaphp_core.c | 15 ++++- drivers/pci/hotplug/rpaphp_pci.c | 1 drivers/pci/hotplug/shpchp_ctrl.c | 16 +++--- 12 files changed, 169 insertions(+), 169 deletions(-) --- a/drivers/pci/hotplug/acpiphp.h +++ b/drivers/pci/hotplug/acpiphp.h @@ -66,7 +66,7 @@ struct slot { char name[SLOT_NAME_SIZE]; }; -/** +/* * struct acpiphp_bridge - PCI bridge information * * for each bridge device in ACPI namespace @@ -97,7 +97,7 @@ struct acpiphp_bridge { }; -/** +/* * struct acpiphp_slot - PCI slot information * * PCI slot information for each *physical* PCI slot @@ -118,7 +118,7 @@ struct acpiphp_slot { }; -/** +/* * struct acpiphp_func - PCI function information * * PCI function information for each object in ACPI namespace @@ -137,7 +137,7 @@ struct acpiphp_func { u32 flags; /* see below */ }; -/** +/* * struct acpiphp_attention_info - device specific attention registration * * ACPI has no generic method of setting/getting attention status --- a/drivers/pci/hotplug/acpiphp_core.c +++ b/drivers/pci/hotplug/acpiphp_core.c @@ -91,10 +91,10 @@ static struct hotplug_slot_ops acpi_hotp * acpiphp_register_attention - set attention LED callback * @info: must be completely filled with LED callbacks * - * Description: this is used to register a hardware specific ACPI + * Description: This is used to register a hardware specific ACPI * driver that manipulates the attention LED. All the fields in * info must be set. - **/ + */ int acpiphp_register_attention(struct acpiphp_attention_info *info) { int retval = -EINVAL; @@ -112,10 +112,10 @@ int acpiphp_register_attention(struct ac * acpiphp_unregister_attention - unset attention LED callback * @info: must match the pointer used to register * - * Description: this is used to un-register a hardware specific acpi + * Description: This is used to un-register a hardware specific acpi * driver that manipulates the attention LED. The pointer to the * info struct must be the same as the one used to set it. - **/ + */ int acpiphp_unregister_attention(struct acpiphp_attention_info *info) { int retval = -EINVAL; @@ -133,7 +133,6 @@ int acpiphp_unregister_attention(struct * @hotplug_slot: slot to enable * * Actual tasks are done in acpiphp_enable_slot() - * */ static int enable_slot(struct hotplug_slot *hotplug_slot) { @@ -151,7 +150,6 @@ static int enable_slot(struct hotplug_sl * @hotplug_slot: slot to disable * * Actual tasks are done in acpiphp_disable_slot() - * */ static int disable_slot(struct hotplug_slot *hotplug_slot) { @@ -168,15 +166,15 @@ static int disable_slot(struct hotplug_s } - /** - * set_attention_status - set attention LED +/** + * set_attention_status - set attention LED * @hotplug_slot: slot to set attention LED on * @status: value to set attention LED to (0 or 1) * * attention status LED, so we use a callback that * was registered with us. This allows hardware specific * ACPI implementations to blink the light for us. - **/ + */ static int set_attention_status(struct hotplug_slot *hotplug_slot, u8 status) { int retval = -ENODEV; @@ -199,7 +197,6 @@ static int disable_slot(struct hotplug_s * * Some platforms may not implement _STA method properly. * In that case, the value returned may not be reliable. - * */ static int get_power_status(struct hotplug_slot *hotplug_slot, u8 *value) { @@ -213,7 +210,7 @@ static int get_power_status(struct hotpl } - /** +/** * get_attention_status - get attention LED status * @hotplug_slot: slot to get status from * @value: returns with value of attention LED @@ -221,8 +218,8 @@ static int get_power_status(struct hotpl * ACPI doesn't have known method to determine the state * of the attention status LED, so we use a callback that * was registered with us. This allows hardware specific - * ACPI implementations to determine its state - **/ + * ACPI implementations to determine its state. + */ static int get_attention_status(struct hotplug_slot *hotplug_slot, u8 *value) { int retval = -EINVAL; @@ -244,8 +241,7 @@ static int get_attention_status(struct h * @value: pointer to store status * * ACPI doesn't provide any formal means to access latch status. - * Instead, we fake latch status from _STA - * + * Instead, we fake latch status from _STA. */ static int get_latch_status(struct hotplug_slot *hotplug_slot, u8 *value) { @@ -265,8 +261,7 @@ static int get_latch_status(struct hotpl * @value: pointer to store status * * ACPI doesn't provide any formal means to access adapter status. - * Instead, we fake adapter status from _STA - * + * Instead, we fake adapter status from _STA. */ static int get_adapter_status(struct hotplug_slot *hotplug_slot, u8 *value) { --- a/drivers/pci/hotplug/acpiphp_glue.c +++ b/drivers/pci/hotplug/acpiphp_glue.c @@ -82,7 +82,6 @@ static void handle_hotplug_event_func(ac * 2. has _PS0 method * 3. has _PS3 method * 4. .. - * */ static int is_ejectable(acpi_handle handle) { @@ -986,10 +985,8 @@ static int power_off_slot(struct acpiphp /** - * acpiphp_max_busnr - return the highest reserved bus number under - * the given bus. + * acpiphp_max_busnr - return the highest reserved bus number under the given bus. * @bus: bus to start search with - * */ static unsigned char acpiphp_max_busnr(struct pci_bus *bus) { @@ -1018,7 +1015,6 @@ static unsigned char acpiphp_max_busnr(s /** * acpiphp_bus_add - add a new bus to acpi subsystem * @func: acpiphp_func of the bridge - * */ static int acpiphp_bus_add(struct acpiphp_func *func) { @@ -1063,7 +1059,6 @@ acpiphp_bus_add_out: /** * acpiphp_bus_trim - trim a bus from acpi subsystem * @handle: handle to acpi namespace - * */ static int acpiphp_bus_trim(acpi_handle handle) { @@ -1089,7 +1084,6 @@ static int acpiphp_bus_trim(acpi_handle * * This function should be called per *physical slot*, * not per each slot object in ACPI namespace. - * */ static int enable_device(struct acpiphp_slot *slot) { @@ -1185,6 +1179,7 @@ static void disable_bridges(struct pci_b /** * disable_device - disable a slot + * @slot: ACPI PHP slot */ static int disable_device(struct acpiphp_slot *slot) { @@ -1240,14 +1235,15 @@ static int disable_device(struct acpiphp /** * get_slot_status - get ACPI slot status + * @slot: ACPI PHP slot * - * if a slot has _STA for each function and if any one of them - * returned non-zero status, return it + * If a slot has _STA for each function and if any one of them + * returned non-zero status, return it. * - * if a slot doesn't have _STA and if any one of its functions' - * configuration space is configured, return 0x0f as a _STA + * If a slot doesn't have _STA and if any one of its functions' + * configuration space is configured, return 0x0f as a _STA. * - * otherwise return 0 + * Otherwise return 0. */ static unsigned int get_slot_status(struct acpiphp_slot *slot) { @@ -1281,6 +1277,7 @@ static unsigned int get_slot_status(stru /** * acpiphp_eject_slot - physically eject the slot + * @slot: ACPI PHP slot */ int acpiphp_eject_slot(struct acpiphp_slot *slot) { @@ -1314,6 +1311,7 @@ int acpiphp_eject_slot(struct acpiphp_sl /** * acpiphp_check_bridge - re-enumerate devices + * @bridge: where to begin re-enumeration * * Iterate over all slots under this bridge and make sure that if a * card is present they are enabled, and if not they are disabled. @@ -1538,13 +1536,11 @@ check_sub_bridges(acpi_handle handle, u3 /** * handle_hotplug_event_bridge - handle ACPI event on bridges - * * @handle: Notify()'ed acpi_handle * @type: Notify code * @context: pointer to acpiphp_bridge structure * - * handles ACPI event notification on {host,p2p} bridges - * + * Handles ACPI event notification on {host,p2p} bridges. */ static void handle_hotplug_event_bridge(acpi_handle handle, u32 type, void *context) { @@ -1634,13 +1630,11 @@ static void handle_hotplug_event_bridge( /** * handle_hotplug_event_func - handle ACPI event on functions (i.e. slots) - * * @handle: Notify()'ed acpi_handle * @type: Notify code * @context: pointer to acpiphp_func structure * - * handles ACPI event notification on slots - * + * Handles ACPI event notification on slots. */ static void handle_hotplug_event_func(acpi_handle handle, u32 type, void *context) { @@ -1705,7 +1699,6 @@ static struct acpi_pci_driver acpi_pci_h /** * acpiphp_glue_init - initializes all PCI hotplug - ACPI glue data structures - * */ int __init acpiphp_glue_init(void) { @@ -1726,7 +1719,7 @@ int __init acpiphp_glue_init(void) /** * acpiphp_glue_exit - terminates all PCI hotplug - ACPI glue data structures * - * This function frees all data allocated in acpiphp_glue_init() + * This function frees all data allocated in acpiphp_glue_init(). */ void acpiphp_glue_exit(void) { @@ -1760,7 +1753,6 @@ int __init acpiphp_get_num_slots(void) * acpiphp_for_each_slot - call function for each slot * @fn: callback function * @data: context to be passed to callback function - * */ static int acpiphp_for_each_slot(acpiphp_callback fn, void *data) { @@ -1786,6 +1778,7 @@ static int acpiphp_for_each_slot(acpiphp /** * acpiphp_enable_slot - power on slot + * @slot: ACPI PHP slot */ int acpiphp_enable_slot(struct acpiphp_slot *slot) { @@ -1815,6 +1808,7 @@ int acpiphp_enable_slot(struct acpiphp_s /** * acpiphp_disable_slot - power off slot + * @slot: ACPI PHP slot */ int acpiphp_disable_slot(struct acpiphp_slot *slot) { --- a/drivers/pci/hotplug/acpiphp_ibm.c +++ b/drivers/pci/hotplug/acpiphp_ibm.c @@ -134,11 +134,11 @@ static struct acpiphp_attention_info ibm * ibm_slot_from_id - workaround for bad ibm hardware * @id: the slot number that linux refers to the slot by * - * Description: this method returns the aCPI slot descriptor + * Description: This method returns the aCPI slot descriptor * corresponding to the Linux slot number. This descriptor * has info about the aPCI slot id and attention status. * This descriptor must be freed using kfree when done. - **/ + */ static union apci_descriptor *ibm_slot_from_id(int id) { int ind = 0, size; @@ -173,9 +173,9 @@ ibm_slot_done: * @slot: the hotplug_slot to work with * @status: what to set the LED to (0 or 1) * - * Description: this method is registered with the acpiphp module as a - * callback to do the device specific task of setting the LED status - **/ + * Description: This method is registered with the acpiphp module as a + * callback to do the device specific task of setting the LED status. + */ static int ibm_set_attention_status(struct hotplug_slot *slot, u8 status) { union acpi_object args[2]; @@ -213,13 +213,13 @@ static int ibm_set_attention_status(stru * @slot: the hotplug_slot to work with * @status: returns what the LED is set to (0 or 1) * - * Description: this method is registered with the acpiphp module as a - * callback to do the device specific task of getting the LED status + * Description: This method is registered with the acpiphp module as a + * callback to do the device specific task of getting the LED status. * * Because there is no direct method of getting the LED status directly * from an ACPI call, we read the aPCI table and parse out our * slot descriptor to read the status from that. - **/ + */ static int ibm_get_attention_status(struct hotplug_slot *slot, u8 *status) { union apci_descriptor *ibm_slot; @@ -245,8 +245,8 @@ static int ibm_get_attention_status(stru * @event: the event info (device specific) * @context: passed context (our notification struct) * - * Description: this method is registered as a callback with the ACPI - * subsystem it is called when this device has an event to notify the OS of + * Description: This method is registered as a callback with the ACPI + * subsystem it is called when this device has an event to notify the OS of. * * The events actually come from the device as two events that get * synthesized into one event with data by this function. The event @@ -256,7 +256,7 @@ static int ibm_get_attention_status(stru * From section 5.6.2.2 of the ACPI 2.0 spec, I understand that the OSPM will * only re-enable the interrupt that causes this event AFTER this method * has returned, thereby enforcing serial access for the notification struct. - **/ + */ static void ibm_handle_events(acpi_handle handle, u32 event, void *context) { u8 detail = event & 0x0f; @@ -279,16 +279,16 @@ static void ibm_handle_events(acpi_handl * ibm_get_table_from_acpi - reads the APLS buffer from ACPI * @bufp: address to pointer to allocate for the table * - * Description: this method reads the APLS buffer in from ACPI and + * Description: This method reads the APLS buffer in from ACPI and * stores the "stripped" table into a single buffer - * it allocates and passes the address back in bufp + * it allocates and passes the address back in bufp. * * If NULL is passed in as buffer, this method only calculates * the size of the table and returns that without filling - * in the buffer + * in the buffer. * - * returns < 0 on error or the size of the table on success - **/ + * Returns < 0 on error or the size of the table on success. + */ static int ibm_get_table_from_acpi(char **bufp) { union acpi_object *package; @@ -349,17 +349,18 @@ read_table_done: /** * ibm_read_apci_table - callback for the sysfs apci_table file * @kobj: the kobject this binary attribute is a part of + * @bin_attr: struct bin_attribute for this file * @buffer: the kernel space buffer to fill * @pos: the offset into the file * @size: the number of bytes requested * - * Description: gets registered with sysfs as the reader callback - * to be executed when /sys/bus/pci/slots/apci_table gets read + * Description: Gets registered with sysfs as the reader callback + * to be executed when /sys/bus/pci/slots/apci_table gets read. * * Since we don't get notified on open and close for this file, * things get really tricky here... - * our solution is to only allow reading the table in all at once - **/ + * our solution is to only allow reading the table in all at once. + */ static ssize_t ibm_read_apci_table(struct kobject *kobj, struct bin_attribute *bin_attr, char *buffer, loff_t pos, size_t size) @@ -385,10 +386,10 @@ static ssize_t ibm_read_apci_table(struc * @context: a pointer to our handle to fill when we find the device * @rv: a return value to fill if desired * - * Description: used as a callback when calling acpi_walk_namespace + * Description: Used as a callback when calling acpi_walk_namespace * to find our device. When this method returns non-zero - * acpi_walk_namespace quits its search and returns our value - **/ + * acpi_walk_namespace quits its search and returns our value. + */ static acpi_status __init ibm_find_acpi_device(acpi_handle handle, u32 lvl, void *context, void **rv) { --- a/drivers/pci/hotplug/cpqphp_core.c +++ b/drivers/pci/hotplug/cpqphp_core.c @@ -117,12 +117,10 @@ static inline int is_slot66mhz(struct sl /** * detect_SMBIOS_pointer - find the System Management BIOS Table in mem region. - * * @begin: begin pointer for region to be scanned. * @end: end pointer for region to be scanned. * - * Returns pointer to the head of the SMBIOS tables (or NULL) - * + * Returns pointer to the head of the SMBIOS tables (or %NULL). */ static void __iomem * detect_SMBIOS_pointer(void __iomem *begin, void __iomem *end) { @@ -157,9 +155,9 @@ static void __iomem * detect_SMBIOS_poin /** * init_SERR - Initializes the per slot SERR generation. + * @ctrl: controller to use * * For unexpected switch opens - * */ static int init_SERR(struct controller * ctrl) { @@ -224,14 +222,15 @@ static int pci_print_IRQ_route (void) /** * get_subsequent_smbios_entry: get the next entry from bios table. - * - * Gets the first entry if previous == NULL - * Otherwise, returns the next entry - * Uses global SMBIOS Table pointer - * + * @smbios_start: where to start in the SMBIOS table + * @smbios_table: location of the SMBIOS table * @curr: %NULL or pointer to previously returned structure * - * returns a pointer to an SMBIOS structure or NULL if none found + * Gets the first entry if previous == NULL; + * otherwise, returns the next entry. + * Uses global SMBIOS Table pointer. + * + * Returns a pointer to an SMBIOS structure or NULL if none found. */ static void __iomem *get_subsequent_smbios_entry(void __iomem *smbios_start, void __iomem *smbios_table, @@ -272,17 +271,18 @@ static void __iomem *get_subsequent_smbi /** - * get_SMBIOS_entry - * - * @type:SMBIOS structure type to be returned + * get_SMBIOS_entry - return the requested SMBIOS entry or %NULL + * @smbios_start: where to start in the SMBIOS table + * @smbios_table: location of the SMBIOS table + * @type: SMBIOS structure type to be returned * @previous: %NULL or pointer to previously returned structure * - * Gets the first entry of the specified type if previous == NULL + * Gets the first entry of the specified type if previous == %NULL; * Otherwise, returns the next entry of the given type. - * Uses global SMBIOS Table pointer - * Uses get_subsequent_smbios_entry + * Uses global SMBIOS Table pointer. + * Uses get_subsequent_smbios_entry. * - * returns a pointer to an SMBIOS structure or %NULL if none found + * Returns a pointer to an SMBIOS structure or %NULL if none found. */ static void __iomem *get_SMBIOS_entry(void __iomem *smbios_start, void __iomem *smbios_table, @@ -581,7 +581,9 @@ get_slot_mapping(struct pci_bus *bus, u8 /** * cpqhp_set_attention_status - Turns the Amber LED for a slot on or off - * + * @ctrl: struct controller to use + * @func: PCI device/function info + * @status: LED control flag: 1 = LED on, 0 = LED off */ static int cpqhp_set_attention_status(struct controller *ctrl, struct pci_func *func, @@ -621,7 +623,8 @@ cpqhp_set_attention_status(struct contro /** * set_attention_status - Turns the Amber LED for a slot on or off - * + * @hotplug_slot: slot to change LED on + * @status: LED control flag */ static int set_attention_status (struct hotplug_slot *hotplug_slot, u8 status) { --- a/drivers/pci/hotplug/cpqphp_ctrl.c +++ b/drivers/pci/hotplug/cpqphp_ctrl.c @@ -123,7 +123,7 @@ static u8 handle_switch_change(u8 change } /** - * cpqhp_find_slot: find the struct slot of given device + * cpqhp_find_slot - find the struct slot of given device * @ctrl: scan lots of this controller * @device: the device id to find */ @@ -305,9 +305,8 @@ static u8 handle_power_fault(u8 change, /** - * sort_by_size: sort nodes on the list by their length, smallest first. + * sort_by_size - sort nodes on the list by their length, smallest first. * @head: list to sort - * */ static int sort_by_size(struct pci_resource **head) { @@ -354,9 +353,8 @@ static int sort_by_size(struct pci_resou /** - * sort_by_max_size: sort nodes on the list by their length, largest first. + * sort_by_max_size - sort nodes on the list by their length, largest first. * @head: list to sort - * */ static int sort_by_max_size(struct pci_resource **head) { @@ -403,8 +401,10 @@ static int sort_by_max_size(struct pci_r /** - * do_pre_bridge_resource_split: find node of resources that are unused - * + * do_pre_bridge_resource_split - find node of resources that are unused + * @head: new list head + * @orig_head: original list head + * @alignment: max node size (?) */ static struct pci_resource *do_pre_bridge_resource_split(struct pci_resource **head, struct pci_resource **orig_head, u32 alignment) @@ -477,8 +477,9 @@ static struct pci_resource *do_pre_bridg /** - * do_bridge_resource_split: find one node of resources that aren't in use - * + * do_bridge_resource_split - find one node of resources that aren't in use + * @head: list head + * @alignment: max node size (?) */ static struct pci_resource *do_bridge_resource_split(struct pci_resource **head, u32 alignment) { @@ -525,14 +526,13 @@ error: /** - * get_io_resource: find first node of given size not in ISA aliasing window. + * get_io_resource - find first node of given size not in ISA aliasing window. * @head: list to search * @size: size of node to find, must be a power of two. * - * Description: this function sorts the resource list by size and then returns + * Description: This function sorts the resource list by size and then returns * returns the first node of "size" length that is not in the ISA aliasing * window. If it finds a node larger than "size" it will split it up. - * */ static struct pci_resource *get_io_resource(struct pci_resource **head, u32 size) { @@ -620,7 +620,7 @@ static struct pci_resource *get_io_resou /** - * get_max_resource: get largest node which has at least the given size. + * get_max_resource - get largest node which has at least the given size. * @head: the list to search the node in * @size: the minimum size of the node to find * @@ -712,7 +712,7 @@ static struct pci_resource *get_max_reso /** - * get_resource: find resource of given size and split up larger ones. + * get_resource - find resource of given size and split up larger ones. * @head: the list to search for resources * @size: the size limit to use * @@ -804,14 +804,14 @@ static struct pci_resource *get_resource /** - * cpqhp_resource_sort_and_combine: sort nodes by base addresses and clean up. + * cpqhp_resource_sort_and_combine - sort nodes by base addresses and clean up * @head: the list to sort and clean up * * Description: Sorts all of the nodes in the list in ascending order by * their base addresses. Also does garbage collection by * combining adjacent nodes. * - * returns 0 if success + * Returns %0 if success. */ int cpqhp_resource_sort_and_combine(struct pci_resource **head) { @@ -951,9 +951,9 @@ irqreturn_t cpqhp_ctrl_intr(int IRQ, voi /** * cpqhp_slot_create - Creates a node and adds it to the proper bus. - * @busnumber - bus where new node is to be located + * @busnumber: bus where new node is to be located * - * Returns pointer to the new node or NULL if unsuccessful + * Returns pointer to the new node or %NULL if unsuccessful. */ struct pci_func *cpqhp_slot_create(u8 busnumber) { @@ -986,7 +986,7 @@ struct pci_func *cpqhp_slot_create(u8 bu * slot_remove - Removes a node from the linked list of slots. * @old_slot: slot to remove * - * Returns 0 if successful, !0 otherwise. + * Returns %0 if successful, !0 otherwise. */ static int slot_remove(struct pci_func * old_slot) { @@ -1026,7 +1026,7 @@ static int slot_remove(struct pci_func * * bridge_slot_remove - Removes a node from the linked list of slots. * @bridge: bridge to remove * - * Returns 0 if successful, !0 otherwise. + * Returns %0 if successful, !0 otherwise. */ static int bridge_slot_remove(struct pci_func *bridge) { @@ -1071,7 +1071,7 @@ out: * cpqhp_slot_find - Looks for a node by bus, and device, multiple functions accessed * @bus: bus to find * @device: device to find - * @index: is 0 for first function found, 1 for the second... + * @index: is %0 for first function found, %1 for the second... * * Returns pointer to the node if successful, %NULL otherwise. */ @@ -1115,16 +1115,13 @@ static int is_bridge(struct pci_func * f /** - * set_controller_speed - set the frequency and/or mode of a specific - * controller segment. - * + * set_controller_speed - set the frequency and/or mode of a specific controller segment. * @ctrl: controller to change frequency/mode for. * @adapter_speed: the speed of the adapter we want to match. * @hp_slot: the slot number where the adapter is installed. * - * Returns 0 if we successfully change frequency and/or mode to match the + * Returns %0 if we successfully change frequency and/or mode to match the * adapter speed. - * */ static u8 set_controller_speed(struct controller *ctrl, u8 adapter_speed, u8 hp_slot) { @@ -1253,13 +1250,14 @@ static u8 set_controller_speed(struct co /** * board_replaced - Called after a board has been replaced in the system. + * @func: PCI device/function information + * @ctrl: hotplug controller * - * This is only used if we don't have resources for hot add - * Turns power on for the board - * Checks to see if board is the same - * If board is same, reconfigures it + * This is only used if we don't have resources for hot add. + * Turns power on for the board. + * Checks to see if board is the same. + * If board is same, reconfigures it. * If board isn't same, turns it back off. - * */ static u32 board_replaced(struct pci_func *func, struct controller *ctrl) { @@ -1403,10 +1401,11 @@ static u32 board_replaced(struct pci_fun /** * board_added - Called after a board has been added to the system. + * @func: PCI device/function info + * @ctrl: hotplug controller * - * Turns power on for the board - * Configures board - * + * Turns power on for the board. + * Configures board. */ static u32 board_added(struct pci_func *func, struct controller *ctrl) { @@ -1607,8 +1606,10 @@ static u32 board_added(struct pci_func * /** - * remove_board - Turns off slot and LED's - * + * remove_board - Turns off slot and LEDs + * @func: PCI device/function info + * @replace_flag: whether replacing or adding a new device + * @ctrl: target controller */ static u32 remove_board(struct pci_func * func, u32 replace_flag, struct controller * ctrl) { @@ -1902,11 +1903,11 @@ static void interrupt_event_handler(stru /** - * cpqhp_pushbutton_thread + * cpqhp_pushbutton_thread - handle pushbutton events + * @slot: target slot (struct) * - * Scheduled procedure to handle blocking stuff for the pushbuttons + * Scheduled procedure to handle blocking stuff for the pushbuttons. * Handles all pending events and exits. - * */ void cpqhp_pushbutton_thread(unsigned long slot) { @@ -2137,9 +2138,10 @@ int cpqhp_process_SS(struct controller * } /** - * switch_leds: switch the leds, go from one site to the other. + * switch_leds - switch the leds, go from one site to the other. * @ctrl: controller to use * @num_of_slots: number of slots to use + * @work_LED: LED control value * @direction: 1 to start from the left side, 0 to start right. */ static void switch_leds(struct controller *ctrl, const int num_of_slots, @@ -2165,11 +2167,11 @@ static void switch_leds(struct controlle } /** - * hardware_test - runs hardware tests + * cpqhp_hardware_test - runs hardware tests + * @ctrl: target controller + * @test_num: the number written to the "test" file in sysfs. * * For hot plug ctrl folks to play with. - * test_num is the number written to the "test" file in sysfs - * */ int cpqhp_hardware_test(struct controller *ctrl, int test_num) { @@ -2249,14 +2251,12 @@ int cpqhp_hardware_test(struct controlle /** * configure_new_device - Configures the PCI header information of one board. - * * @ctrl: pointer to controller structure * @func: pointer to function structure * @behind_bridge: 1 if this is a recursive call, 0 if not * @resources: pointer to set of resource lists * - * Returns 0 if success - * + * Returns 0 if success. */ static u32 configure_new_device(struct controller * ctrl, struct pci_func * func, u8 behind_bridge, struct resource_lists * resources) @@ -2346,15 +2346,13 @@ static u32 configure_new_device(struct c /** * configure_new_function - Configures the PCI header information of one device - * * @ctrl: pointer to controller structure * @func: pointer to function structure * @behind_bridge: 1 if this is a recursive call, 0 if not * @resources: pointer to set of resource lists * * Calls itself recursively for bridged devices. - * Returns 0 if success - * + * Returns 0 if success. */ static int configure_new_function(struct controller *ctrl, struct pci_func *func, u8 behind_bridge, --- a/drivers/pci/hotplug/fakephp.c +++ b/drivers/pci/hotplug/fakephp.c @@ -165,11 +165,11 @@ static void remove_slot(struct dummy_slo } /** - * Rescan slot. - * Tries hard not to re-enable already existing devices - * also handles scanning of subfunctions + * pci_rescan_slot - Rescan slot + * @temp: Device template. Should be set: bus and devfn. * - * @param temp Device template. Should be set: bus and devfn. + * Tries hard not to re-enable already existing devices; + * also handles scanning of subfunctions. */ static void pci_rescan_slot(struct pci_dev *temp) { @@ -229,10 +229,10 @@ static void pci_rescan_slot(struct pci_d /** - * Rescan PCI bus. - * call pci_rescan_slot for each possible function of the bus + * pci_rescan_bus - Rescan PCI bus + * @bus: the PCI bus to rescan * - * @param bus + * Call pci_rescan_slot for each possible function of the bus. */ static void pci_rescan_bus(const struct pci_bus *bus) { --- a/drivers/pci/hotplug/pciehp_ctrl.c +++ b/drivers/pci/hotplug/pciehp_ctrl.c @@ -208,10 +208,10 @@ static void set_slot_off(struct controll /** * board_added - Called after a board has been added to the system. + * @p_slot: &slot where board is added * - * Turns power on for the board - * Configures board - * + * Turns power on for the board. + * Configures board. */ static int board_added(struct slot *p_slot) { @@ -276,8 +276,8 @@ err_exit: } /** - * remove_board - Turns off slot and LED's - * + * remove_board - Turns off slot and LEDs + * @p_slot: slot where board is being removed */ static int remove_board(struct slot *p_slot) { @@ -319,11 +319,11 @@ struct power_work_info { }; /** - * pciehp_pushbutton_thread + * pciehp_power_thread - handle pushbutton events + * @work: &struct work_struct describing work to be done * - * Scheduled procedure to handle blocking stuff for the pushbuttons + * Scheduled procedure to handle blocking stuff for the pushbuttons. * Handles all pending events and exits. - * */ static void pciehp_power_thread(struct work_struct *work) { --- a/drivers/pci/hotplug/rpadlpar_core.c +++ b/drivers/pci/hotplug/rpadlpar_core.c @@ -100,6 +100,7 @@ static struct device_node *find_dlpar_no /** * find_php_slot - return hotplug slot structure for device node + * @dn: target &device_node * * This routine will return the hotplug slot structure * for a given device node. Note that built-in PCI slots @@ -293,9 +294,8 @@ static int dlpar_add_vio_slot(char *drc_ * dlpar_add_slot - DLPAR add an I/O Slot * @drc_name: drc-name of newly added slot * - * Make the hotplug module and the kernel aware - * of a newly added I/O Slot. - * Return Codes - + * Make the hotplug module and the kernel aware of a newly added I/O Slot. + * Return Codes: * 0 Success * -ENODEV Not a valid drc_name * -EINVAL Slot already added @@ -339,9 +339,9 @@ exit: /** * dlpar_remove_vio_slot - DLPAR remove a virtual I/O Slot * @drc_name: drc-name of newly added slot + * @dn: &device_node * - * Remove the kernel and hotplug representations - * of an I/O Slot. + * Remove the kernel and hotplug representations of an I/O Slot. * Return Codes: * 0 Success * -EINVAL Vio dev doesn't exist @@ -359,11 +359,11 @@ static int dlpar_remove_vio_slot(char *d } /** - * dlpar_remove_slot - DLPAR remove a PCI I/O Slot + * dlpar_remove_pci_slot - DLPAR remove a PCI I/O Slot * @drc_name: drc-name of newly added slot + * @dn: &device_node * - * Remove the kernel and hotplug representations - * of a PCI I/O Slot. + * Remove the kernel and hotplug representations of a PCI I/O Slot. * Return Codes: * 0 Success * -ENODEV Not a valid drc_name @@ -405,8 +405,7 @@ int dlpar_remove_pci_slot(char *drc_name * dlpar_remove_slot - DLPAR remove an I/O Slot * @drc_name: drc-name of newly added slot * - * Remove the kernel and hotplug representations - * of an I/O Slot. + * Remove the kernel and hotplug representations of an I/O Slot. * Return Codes: * 0 Success * -ENODEV Not a valid drc_name --- a/drivers/pci/hotplug/rpaphp_core.c +++ b/drivers/pci/hotplug/rpaphp_core.c @@ -54,10 +54,12 @@ module_param(debug, bool, 0644); /** * set_attention_status - set attention LED + * @hotplug_slot: target &hotplug_slot + * @value: LED control value + * * echo 0 > attention -- set LED OFF * echo 1 > attention -- set LED ON * echo 2 > attention -- set LED ID(identify, light is blinking) - * */ static int set_attention_status(struct hotplug_slot *hotplug_slot, u8 value) { @@ -99,6 +101,8 @@ static int get_power_status(struct hotpl /** * get_attention_status - get attention LED status + * @hotplug_slot: slot to get status + * @value: pointer to store status */ static int get_attention_status(struct hotplug_slot *hotplug_slot, u8 * value) { @@ -254,6 +258,11 @@ static int is_php_type(char *drc_type) /** * is_php_dn() - return 1 if this is a hotpluggable pci slot, else 0 + * @dn: target &device_node + * @indexes: passed to get_children_props() + * @names: passed to get_children_props() + * @types: returned from get_children_props() + * @power_domains: * * This routine will return true only if the device node is * a hotpluggable slot. This routine will return false @@ -279,7 +288,7 @@ static int is_php_dn(struct device_node /** * rpaphp_add_slot -- declare a hotplug slot to the hotplug subsystem. - * @dn device node of slot + * @dn: device node of slot * * This subroutine will register a hotplugable slot with the * PCI hotplug infrastructure. This routine is typicaly called @@ -291,7 +300,7 @@ static int is_php_dn(struct device_node * routine will just return without doing anything, since embedded * slots cannot be hotplugged. * - * To remove a slot, it suffices to call rpaphp_deregister_slot() + * To remove a slot, it suffices to call rpaphp_deregister_slot(). */ int rpaphp_add_slot(struct device_node *dn) { --- a/drivers/pci/hotplug/rpaphp_pci.c +++ b/drivers/pci/hotplug/rpaphp_pci.c @@ -79,6 +79,7 @@ static void set_slot_name(struct slot *s /** * rpaphp_enable_slot - record slot state, config pci device + * @slot: target &slot * * Initialize values in the slot, and the hotplug_slot info * structures to indicate if there is a pci card plugged into --- a/drivers/pci/hotplug/shpchp_ctrl.c +++ b/drivers/pci/hotplug/shpchp_ctrl.c @@ -231,10 +231,10 @@ static int fix_bus_speed(struct controll /** * board_added - Called after a board has been added to the system. + * @p_slot: target &slot * - * Turns power on for the board - * Configures board - * + * Turns power on for the board. + * Configures board. */ static int board_added(struct slot *p_slot) { @@ -350,8 +350,8 @@ err_exit: /** - * remove_board - Turns off slot and LED's - * + * remove_board - Turns off slot and LEDs + * @p_slot: target &slot */ static int remove_board(struct slot *p_slot) { @@ -397,11 +397,11 @@ struct pushbutton_work_info { }; /** - * shpchp_pushbutton_thread + * shpchp_pushbutton_thread - handle pushbutton events + * @work: &struct work_struct to be handled * - * Scheduled procedure to handle blocking stuff for the pushbuttons + * Scheduled procedure to handle blocking stuff for the pushbuttons. * Handles all pending events and exits. - * */ static void shpchp_pushbutton_thread(struct work_struct *work) {