@@ -292,15 +292,17 @@ static int ctrl_slot_cleanup(struct controller *ctrl)
/**
- * get_slot_mapping - determine logical slot mapping for PCI device
+ * get_slot_mapping - Determine logical slot mapping for PCI device.
+ * @bus: Pointer to the PCI bus structure.
+ * @bus_num: Bus number of the PCI device.
+ * @dev_num: Device number of the PCI device.
+ * @slot: Pointer to where slot number will be returned.
*
- * Won't work for more than one PCI-PCI bridge in a slot.
+ * Will not work for more than one PCI-PCI bridge in a slot.
*
- * @bus_num - bus number of PCI device
- * @dev_num - device number of PCI device
- * @slot - Pointer to u8 where slot number will be returned
- *
- * Output: SUCCESS or FAILURE
+ * Return:
+ * * 0 - Logical slot mapping has been found for this PCI device.
+ * * < 0 - Unable to find entry in the routing table for this PCI device.
*/
static int
get_slot_mapping(struct pci_bus *bus, u8 bus_num, u8 dev_num, u8 *slot)
@@ -1876,8 +1876,8 @@ static void interrupt_event_handler(struct controller *ctrl)
/**
- * cpqhp_pushbutton_thread - handle pushbutton events
- * @slot: target slot (struct)
+ * cpqhp_pushbutton_thread - Handle pushbutton events.
+ * @t: Pointer to struct timer_list which holds all timer related callbacks.
*
* Scheduled procedure to handle blocking stuff for the pushbuttons.
* Handles all pending events and exits.
@@ -44,38 +44,54 @@ extern int pciehp_poll_time;
#define SLOT_NAME_SIZE 10
/**
- * struct controller - PCIe hotplug controller
- * @pcie: pointer to the controller's PCIe port service device
- * @slot_cap: cached copy of the Slot Capabilities register
- * @slot_ctrl: cached copy of the Slot Control register
- * @ctrl_lock: serializes writes to the Slot Control register
- * @cmd_started: jiffies when the Slot Control register was last written;
- * the next write is allowed 1 second later, absent a Command Completed
- * interrupt (PCIe r4.0, sec 6.7.3.2)
- * @cmd_busy: flag set on Slot Control register write, cleared by IRQ handler
- * on reception of a Command Completed event
- * @queue: wait queue to wake up on reception of a Command Completed event,
- * used for synchronous writes to the Slot Control register
- * @pending_events: used by the IRQ handler to save events retrieved from the
- * Slot Status register for later consumption by the IRQ thread
- * @notification_enabled: whether the IRQ was requested successfully
- * @power_fault_detected: whether a power fault was detected by the hardware
- * that has not yet been cleared by the user
- * @poll_thread: thread to poll for slot events if no IRQ is available,
- * enabled with pciehp_poll_mode module parameter
- * @state: current state machine position
- * @state_lock: protects reads and writes of @state;
- * protects scheduling, execution and cancellation of @button_work
- * @button_work: work item to turn the slot on or off after 5 seconds
- * in response to an Attention Button press
- * @hotplug_slot: structure registered with the PCI hotplug core
- * @reset_lock: prevents access to the Data Link Layer Link Active bit in the
- * Link Status register and to the Presence Detect State bit in the Slot
- * Status register during a slot reset which may cause them to flap
- * @ist_running: flag to keep user request waiting while IRQ thread is running
- * @request_result: result of last user request submitted to the IRQ thread
- * @requester: wait queue to wake up on completion of user request,
- * used for synchronous slot enable/disable request via sysfs
+ * struct controller - PCIe hotplug controller.
+ * @pcie: Pointer to the controller's PCIe port service
+ * device.
+ * @slot_cap: Cached copy of the Slot Capabilities register.
+ * @inband_presence_disabled: Flag to used to track whether the in-band
+ * presence detection is disabled.
+ * @slot_ctrl: Cached copy of the Slot Control register.
+ * @ctrl_lock: Serializes writes to the Slot Control register.
+ * @cmd_started: Jiffies when the Slot Control register was last
+ * written; the next write is allowed 1 second
+ * later, absent a Command Completed interrupt
+ * (PCIe r4.0, sec 6.7.3.2).
+ * @cmd_busy: Flag set on Slot Control register write, cleared
+ * by IRQ handler on reception of a Command
+ * Completed event.
+ * @queue: Wait queue to wake up on reception of a Command
+ * Completed event, used for synchronous writes to
+ * the Slot Control register.
+ * @pending_events: Used by the IRQ handler to save events retrieved
+ * from the Slot Status register for later
+ * consumption by the IRQ thread.
+ * @notification_enabled: Whether the IRQ was requested successfully.
+ * @power_fault_detected: Whether a power fault was detected by the
+ * hardware that has not yet been cleared by the
+ * user.
+ * @poll_thread: Thread to poll for slot events if no IRQ is
+ * available, enabled with pciehp_poll_mode module
+ * parameter.
+ * @state: Current state machine position.
+ * @state_lock: Protects reads and writes of @state; protects
+ * scheduling, execution and cancellation of
+ * @button_work.
+ * @button_work: Work item to turn the slot on or off after
+ * 5 seconds in response to an Attention Button
+ * press.
+ * @hotplug_slot: Structure registered with the PCI hotplug core.
+ * @reset_lock: Prevents access to the Data Link Layer Link
+ * Active bit in the Link Status register and to
+ * the Presence Detect State bit in the Slot Status
+ * register during a slot reset which may cause
+ * them to flap.
+ * @ist_running: Flag to keep user request waiting while IRQ
+ * thread is running.
+ * @request_result: Result of last user request submitted to the IRQ
+ * thread.
+ * @requester: Wait queue to wake up on completion of user
+ * request, used for synchronous slot
+ * enable/disable request via sysfs.
*
* PCIe hotplug has a 1:1 relationship between controller and slot, hence
* unlike other drivers, the two aren't represented by separate structures.
Fix kernel-doc formatting and add missing documentation for the parameters "bus" of the get_slot_mapping() function, "t" of the cpqhp_pushbutton_thread() function and "controller" of the inband_presence_disabled() function. Also remove surplus parameter "slot" from the description of the function cpqhp_pushbutton_thread(). Thus, resolve build time warnings related to kernel-doc: drivers/pci/hotplug/cpqphp_core.c:308: warning: Function parameter or member 'bus' not described in 'get_slot_mapping' drivers/pci/hotplug/cpqphp_core.c:308: warning: Function parameter or member 'bus_num' not described in 'get_slot_mapping' drivers/pci/hotplug/cpqphp_core.c:308: warning: Function parameter or member 'dev_num' not described in 'get_slot_mapping' drivers/pci/hotplug/cpqphp_core.c:308: warning: Function parameter or member 'slot' not described in 'get_slot_mapping' drivers/pci/hotplug/cpqphp_ctrl.c:1887: warning: Function parameter or member 't' not described in 'cpqhp_pushbutton_thread' drivers/pci/hotplug/cpqphp_ctrl.c:1887: warning: Excess function parameter 'slot' description in 'cpqhp_pushbutton_thread' drivers/pci/hotplug/pciehp.h:110: warning: Function parameter or member 'inband_presence_disabled' not described in 'controller' No change to functionality intended. Signed-off-by: Krzysztof Wilczyński <kw@linux.com> --- drivers/pci/hotplug/cpqphp_core.c | 16 ++++--- drivers/pci/hotplug/cpqphp_ctrl.c | 4 +- drivers/pci/hotplug/pciehp.h | 80 ++++++++++++++++++------------- 3 files changed, 59 insertions(+), 41 deletions(-)