Commit 0c169edf authored by Thomas Gleixner's avatar Thomas Gleixner
Browse files

genirq/manage: Cleanup kernel doc comments 



Get rid of the extra tab to make it consistent.

Signed-off-by: default avatarThomas Gleixner <tglx@linutronix.de>
Acked-by: default avatarPeter Zijlstra (Intel) <peterz@infradead.org>
Link: https://lore.kernel.org/all/20250429065421.710273122@linutronix.de
parent 95a36458

kernel/irq/manage.c

+271 −289
Original line number Diff line number Diff line
@@ -79,23 +79,22 @@ static void __synchronize_hardirq(struct irq_desc *desc, bool sync_chip) 
 * synchronize_hardirq - wait for pending hard IRQ handlers (on other CPUs)

 * @irq: interrupt number to wait for

 *

 *	This function waits for any pending hard IRQ handlers for this

 *	interrupt to complete before returning. If you use this

 *	function while holding a resource the IRQ handler may need you

 *	will deadlock. It does not take associated threaded handlers

 *	into account.

 * This function waits for any pending hard IRQ handlers for this interrupt

 * to complete before returning. If you use this function while holding a

 * resource the IRQ handler may need you will deadlock. It does not take

 * associated threaded handlers into account.

 *

 *	Do not use this for shutdown scenarios where you must be sure

 *	that all parts (hardirq and threaded handler) have completed.

 * Do not use this for shutdown scenarios where you must be sure that all

 * parts (hardirq and threaded handler) have completed.

 *

 * Returns: false if a threaded handler is active.

 *

 * This function may be called - with care - from IRQ context.

 *

 * It does not check whether there is an interrupt in flight at the

 *	hardware level, but not serviced yet, as this might deadlock when

 *	called with interrupts disabled and the target CPU of the interrupt

 *	is the current CPU.

 * hardware level, but not serviced yet, as this might deadlock when called

 * with interrupts disabled and the target CPU of the interrupt is the

 * current CPU.

 */

bool synchronize_hardirq(unsigned int irq)

{
@@ -124,9 +123,9 @@ static void __synchronize_irq(struct irq_desc *desc) 
 * synchronize_irq - wait for pending IRQ handlers (on other CPUs)

 * @irq: interrupt number to wait for

 *

 *	This function waits for any pending IRQ handlers for this interrupt

 *	to complete before returning. If you use this function while

 *	holding a resource the IRQ handler may need you will deadlock.

 * This function waits for any pending IRQ handlers for this interrupt to

 * complete before returning. If you use this function while holding a

 * resource the IRQ handler may need you will deadlock.

 *

 * Can only be called from preemptible code as it might sleep when

 * an interrupt thread is associated to @irq.
@@ -184,10 +183,10 @@ bool irq_can_set_affinity_usr(unsigned int irq) 
 * irq_set_thread_affinity - Notify irq threads to adjust affinity

 * @desc:	irq descriptor which has affinity changed

 *

 *	We just set IRQTF_AFFINITY and delegate the affinity setting

 *	to the interrupt thread itself. We can not call

 *	set_cpus_allowed_ptr() here as we hold desc->lock and this

 *	code can be called from hard interrupt context.

 * Just set IRQTF_AFFINITY and delegate the affinity setting to the

 * interrupt thread itself. We can not call set_cpus_allowed_ptr() here as

 * we hold desc->lock and this code can be called from hard interrupt

 * context.

 */

static void irq_set_thread_affinity(struct irq_desc *desc)

{
@@ -550,11 +549,10 @@ static void irq_affinity_notify(struct work_struct *work) 
 *		the other fields will be initialised by this function.

 *

 * Must be called in process context.  Notification may only be enabled

 *	after the IRQ is allocated and must be disabled before the IRQ is

 *	freed using free_irq().

 * after the IRQ is allocated and must be disabled before the IRQ is freed

 * using free_irq().

 */

int

irq_set_affinity_notifier(unsigned int irq, struct irq_affinity_notify *notify)

int irq_set_affinity_notifier(unsigned int irq, struct irq_affinity_notify *notify)

{

	struct irq_desc *desc = irq_to_desc(irq);

	struct irq_affinity_notify *old_notify;
@@ -650,10 +648,9 @@ int irq_setup_affinity(struct irq_desc *desc) 
 * @vcpu_info:	vCPU specific data or pointer to a percpu array of vCPU

 *		specific data for percpu_devid interrupts

 *

 *	This function uses the vCPU specific data to set the vCPU

 *	affinity for an irq. The vCPU specific data is passed from

 *	outside, such as KVM. One example code path is as below:

 *	KVM -> IOMMU -> irq_set_vcpu_affinity().

 * This function uses the vCPU specific data to set the vCPU affinity for

 * an irq. The vCPU specific data is passed from outside, such as KVM. One

 * example code path is as below: KVM -> IOMMU -> irq_set_vcpu_affinity().

 */

int irq_set_vcpu_affinity(unsigned int irq, void *vcpu_info)

{
@@ -725,14 +722,14 @@ EXPORT_SYMBOL(disable_irq_nosync); 
 * disable_irq - disable an irq and wait for completion

 * @irq: Interrupt to disable

 *

 *	Disable the selected interrupt line.  Enables and Disables are

 *	nested.

 *	This function waits for any pending IRQ handlers for this interrupt

 *	to complete before returning. If you use this function while

 *	holding a resource the IRQ handler may need you will deadlock.

 * Disable the selected interrupt line.  Enables and Disables are nested.

 *

 *	Can only be called from preemptible code as it might sleep when

 *	an interrupt thread is associated to @irq.

 * This function waits for any pending IRQ handlers for this interrupt to

 * complete before returning. If you use this function while holding a

 * resource the IRQ handler may need you will deadlock.

 *

 * Can only be called from preemptible code as it might sleep when an

 * interrupt thread is associated to @irq.

 *

 */

void disable_irq(unsigned int irq)
@@ -747,14 +744,14 @@ EXPORT_SYMBOL(disable_irq); 
 * disable_hardirq - disables an irq and waits for hardirq completion

 * @irq: Interrupt to disable

 *

 *	Disable the selected interrupt line.  Enables and Disables are

 *	nested.

 *	This function waits for any pending hard IRQ handlers for this

 *	interrupt to complete before returning. If you use this function while

 *	holding a resource the hard IRQ handler may need you will deadlock.

 * Disable the selected interrupt line.  Enables and Disables are nested.

 *

 *	When used to optimistically disable an interrupt from atomic context

 *	the return value must be checked.

 * This function waits for any pending hard IRQ handlers for this interrupt

 * to complete before returning. If you use this function while holding a

 * resource the hard IRQ handler may need you will deadlock.

 *

 * When used to optimistically disable an interrupt from atomic context the

 * return value must be checked.

 *

 * Returns: false if a threaded handler is active.

 *
@@ -764,7 +761,6 @@ bool disable_hardirq(unsigned int irq) 
{

	if (!__disable_irq_nosync(irq))

		return synchronize_hardirq(irq);



	return false;

}

EXPORT_SYMBOL_GPL(disable_hardirq);
@@ -773,8 +769,8 @@ EXPORT_SYMBOL_GPL(disable_hardirq); 
 * disable_nmi_nosync - disable an nmi without waiting

 * @irq: Interrupt to disable

 *

 *	Disable the selected interrupt line. Disables and enables are

 *	nested.

 * Disable the selected interrupt line. Disables and enables are nested.

 *

 * The interrupt to disable must have been requested through request_nmi.

 * Unlike disable_nmi(), this function does not ensure existing

 * instances of the IRQ handler have completed before returning.
@@ -820,9 +816,8 @@ void __enable_irq(struct irq_desc *desc) 
 * enable_irq - enable handling of an irq

 * @irq: Interrupt to enable

 *

 *	Undoes the effect of one call to disable_irq().  If this

 *	matches the last disable, processing of interrupts on this

 *	IRQ line is re-enabled.

 * Undoes the effect of one call to disable_irq().  If this matches the

 * last disable, processing of interrupts on this IRQ line is re-enabled.

 *

 * This function may be called from IRQ context only when

 * desc->irq_data.chip->bus_lock and desc->chip->bus_sync_unlock are NULL !
@@ -849,9 +844,8 @@ EXPORT_SYMBOL(enable_irq); 
 * @irq: Interrupt to enable

 *

 * The interrupt to enable must have been requested through request_nmi.

 *	Undoes the effect of one call to disable_nmi(). If this

 *	matches the last disable, processing of interrupts on this

 *	IRQ line is re-enabled.

 * Undoes the effect of one call to disable_nmi(). If this matches the last

 * disable, processing of interrupts on this IRQ line is re-enabled.

 */

void enable_nmi(unsigned int irq)

{
@@ -877,19 +871,18 @@ static int set_irq_wake_real(unsigned int irq, unsigned int on) 
 * @irq:	interrupt to control

 * @on:	enable/disable power management wakeup

 *

 *	Enable/disable power management wakeup mode, which is

 *	disabled by default.  Enables and disables must match,

 *	just as they match for non-wakeup mode support.

 * Enable/disable power management wakeup mode, which is disabled by

 * default.  Enables and disables must match, just as they match for

 * non-wakeup mode support.

 *

 *	Wakeup mode lets this IRQ wake the system from sleep

 *	states like "suspend to RAM".

 * Wakeup mode lets this IRQ wake the system from sleep states like

 * "suspend to RAM".

 *

 *	Note: irq enable/disable state is completely orthogonal

 *	to the enable/disable state of irq wake. An irq can be

 *	disabled with disable_irq() and still wake the system as

 *	long as the irq has wake enabled. If this does not hold,

 *	then the underlying irq chip and the related driver need

 *	to be investigated.

 * Note: irq enable/disable state is completely orthogonal to the

 * enable/disable state of irq wake. An irq can be disabled with

 * disable_irq() and still wake the system as long as the irq has wake

 * enabled. If this does not hold, then the underlying irq chip and the

 * related driver need to be investigated.

 */

int irq_set_irq_wake(unsigned int irq, unsigned int on)

{
@@ -1337,7 +1330,6 @@ static int irq_thread(void *data) 
 * irq_wake_thread - wake the irq thread for the action identified by dev_id

 * @irq:	Interrupt line

 * @dev_id:	Device identity for which the thread should be woken

 *

 */

void irq_wake_thread(unsigned int irq, void *dev_id)

{
@@ -2009,12 +2001,11 @@ static struct irqaction *__free_irq(struct irq_desc *desc, void *dev_id) 
 * @irq:	Interrupt line to free

 * @dev_id:	Device identity to free

 *

 *	Remove an interrupt handler. The handler is removed and if the

 *	interrupt line is no longer in use by any driver it is disabled.

 *	On a shared IRQ the caller must ensure the interrupt is disabled

 *	on the card it drives before calling this function. The function

 *	does not return until any executing interrupts for this IRQ

 *	have completed.

 * Remove an interrupt handler. The handler is removed and if the interrupt

 * line is no longer in use by any driver it is disabled.  On a shared IRQ

 * the caller must ensure the interrupt is disabled on the card it drives

 * before calling this function. The function does not return until any

 * executing interrupts for this IRQ have completed.

 *

 * This function must not be called from interrupt context.

 *
@@ -2111,28 +2102,26 @@ const void *free_nmi(unsigned int irq, void *dev_id) 
 * @devname:	An ascii name for the claiming device

 * @dev_id:	A cookie passed back to the handler function

 *

 *	This call allocates interrupt resources and enables the

 *	interrupt line and IRQ handling. From the point this

 *	call is made your handler function may be invoked. Since

 *	your handler function must clear any interrupt the board

 *	raises, you must take care both to initialise your hardware

 *	and to set up the interrupt handler in the right order.

 *

 *	If you want to set up a threaded irq handler for your device

 *	then you need to supply @handler and @thread_fn. @handler is

 *	still called in hard interrupt context and has to check

 *	whether the interrupt originates from the device. If yes it

 *	needs to disable the interrupt on the device and return

 *	IRQ_WAKE_THREAD which will wake up the handler thread and run

 *	@thread_fn. This split handler design is necessary to support

 *	shared interrupts.

 *

 *	Dev_id must be globally unique. Normally the address of the

 *	device data structure is used as the cookie. Since the handler

 *	receives this value it makes sense to use it.

 *

 *	If your interrupt is shared you must pass a non NULL dev_id

 *	as this is required when freeing the interrupt.

 * This call allocates interrupt resources and enables the interrupt line

 * and IRQ handling. From the point this call is made your handler function

 * may be invoked. Since your handler function must clear any interrupt the

 * board raises, you must take care both to initialise your hardware and to

 * set up the interrupt handler in the right order.

 *

 * If you want to set up a threaded irq handler for your device then you

 * need to supply @handler and @thread_fn. @handler is still called in hard

 * interrupt context and has to check whether the interrupt originates from

 * the device. If yes it needs to disable the interrupt on the device and

 * return IRQ_WAKE_THREAD which will wake up the handler thread and run

 * @thread_fn. This split handler design is necessary to support shared

 * interrupts.

 *

 * @dev_id must be globally unique. Normally the address of the device data

 * structure is used as the cookie. Since the handler receives this value

 * it makes sense to use it.

 *

 * If your interrupt is shared you must pass a non NULL dev_id as this is

 * required when freeing the interrupt.

 *

 * Flags:

 *
@@ -2240,13 +2229,12 @@ EXPORT_SYMBOL(request_threaded_irq); 
 * @name:	An ascii name for the claiming device

 * @dev_id:	A cookie passed back to the handler function

 *

 *	This call allocates interrupt resources and enables the

 *	interrupt line and IRQ handling. It selects either a

 *	hardirq or threaded handling method depending on the

 *	context.

 * This call allocates interrupt resources and enables the interrupt line

 * and IRQ handling. It selects either a hardirq or threaded handling

 * method depending on the context.

 *

 *	On failure, it returns a negative value. On success,

 *	it returns either IRQC_IS_HARDIRQ or IRQC_IS_NESTED.

 * Returns: On failure, it returns a negative value. On success, it returns either

 * IRQC_IS_HARDIRQ or IRQC_IS_NESTED.

 */

int request_any_context_irq(unsigned int irq, irq_handler_t handler,

			    unsigned long flags, const char *name, void *dev_id)
@@ -2281,9 +2269,8 @@ EXPORT_SYMBOL_GPL(request_any_context_irq); 
 * @name:	An ascii name for the claiming device

 * @dev_id:	A cookie passed back to the handler function

 *

 *	This call allocates interrupt resources and enables the

 *	interrupt line and IRQ handling. It sets up the IRQ line

 *	to be handled as an NMI.

 * This call allocates interrupt resources and enables the interrupt line

 * and IRQ handling. It sets up the IRQ line to be handled as an NMI.

 *

 * An interrupt line delivering NMIs cannot be shared and IRQ handling

 * cannot be threaded.
@@ -2291,12 +2278,12 @@ EXPORT_SYMBOL_GPL(request_any_context_irq); 
 * Interrupt lines requested for NMI delivering must produce per cpu

 * interrupts and have auto enabling setting disabled.

 *

 *	Dev_id must be globally unique. Normally the address of the

 *	device data structure is used as the cookie. Since the handler

 *	receives this value it makes sense to use it.

 * @dev_id must be globally unique. Normally the address of the device data

 * structure is used as the cookie. Since the handler receives this value

 * it makes sense to use it.

 *

 *	If the interrupt line cannot be used to deliver NMIs, function

 *	will fail and return a negative value.

 * If the interrupt line cannot be used to deliver NMIs, function will fail

 * and return a negative value.

 */

int request_nmi(unsigned int irq, irq_handler_t handler,

		unsigned long irqflags, const char *name, void *dev_id)
@@ -2517,10 +2504,10 @@ void remove_percpu_irq(unsigned int irq, struct irqaction *act) 
 * @irq:	Interrupt line to free

 * @dev_id:	Device identity to free

 *

 *	Remove a percpu interrupt handler. The handler is removed, but

 *	the interrupt line is not disabled. This must be done on each

 *	CPU before calling this function. The function does not return

 *	until any executing interrupts for this IRQ have completed.

 * Remove a percpu interrupt handler. The handler is removed, but the

 * interrupt line is not disabled. This must be done on each CPU before

 * calling this function. The function does not return until any executing

 * interrupts for this IRQ have completed.

 *

 * This function must not be called from interrupt context.

 */
@@ -2585,12 +2572,11 @@ int setup_percpu_irq(unsigned int irq, struct irqaction *act) 
 * @devname:	An ascii name for the claiming device

 * @dev_id:	A percpu cookie passed back to the handler function

 *

 *	This call allocates interrupt resources and enables the

 *	interrupt on the local CPU. If the interrupt is supposed to be

 *	enabled on other CPUs, it has to be done on each CPU using

 *	enable_percpu_irq().

 * This call allocates interrupt resources and enables the interrupt on the

 * local CPU. If the interrupt is supposed to be enabled on other CPUs, it

 * has to be done on each CPU using enable_percpu_irq().

 *

 *	Dev_id must be globally unique. It is a per-cpu variable, and

 * @dev_id must be globally unique. It is a per-cpu variable, and

 * the handler gets called with the interrupted CPU's instance of

 * that variable.

 */
@@ -2650,9 +2636,9 @@ EXPORT_SYMBOL_GPL(__request_percpu_irq); 
 * have to be setup on each CPU by calling prepare_percpu_nmi() before

 * being enabled on the same CPU by using enable_percpu_nmi().

 *

 *	Dev_id must be globally unique. It is a per-cpu variable, and

 *	the handler gets called with the interrupted CPU's instance of

 *	that variable.

 * @dev_id must be globally unique. It is a per-cpu variable, and the

 * handler gets called with the interrupted CPU's instance of that

 * variable.

 *

 * Interrupt lines requested for NMI delivering should have auto enabling

 * setting disabled.
@@ -2725,8 +2711,8 @@ int request_percpu_nmi(unsigned int irq, irq_handler_t handler, 
 * As a CPU local operation, this should be called from non-preemptible

 * context.

 *

 *	If the interrupt line cannot be used to deliver NMIs, function

 *	will fail returning a negative value.

 * If the interrupt line cannot be used to deliver NMIs, function will fail

 * returning a negative value.

 */

int prepare_percpu_nmi(unsigned int irq)

{
@@ -2761,13 +2747,11 @@ int prepare_percpu_nmi(unsigned int irq) 


/**

 * teardown_percpu_nmi - undoes NMI setup of IRQ line

 *	@irq: Interrupt line from which CPU local NMI configuration should be

 *	      removed

 * @irq: Interrupt line from which CPU local NMI configuration should be removed

 *

 * This call undoes the setup done by prepare_percpu_nmi().

 *

 * IRQ line should not be enabled for the current CPU.

 *

 * As a CPU local operation, this should be called from non-preemptible

 * context.

 */
@@ -2820,12 +2804,11 @@ static int __irq_get_irqchip_state(struct irq_data *data, enum irqchip_irq_state 
 * @which:	One of IRQCHIP_STATE_* the caller wants to know about

 * @state:	a pointer to a boolean where the state is to be stored

 *

 *	This call snapshots the internal irqchip state of an

 *	interrupt, returning into @state the bit corresponding to

 *	stage @which

 * This call snapshots the internal irqchip state of an interrupt,

 * returning into @state the bit corresponding to stage @which

 *

 *	This function should be called with preemption disabled if the

 *	interrupt controller has per-cpu registers.

 * This function should be called with preemption disabled if the interrupt

 * controller has per-cpu registers.

 */

int irq_get_irqchip_state(unsigned int irq, enum irqchip_irq_state which,

			  bool *state)
@@ -2854,14 +2837,13 @@ EXPORT_SYMBOL_GPL(irq_get_irqchip_state); 
 * @which:	State to be restored (one of IRQCHIP_STATE_*)

 * @val:	Value corresponding to @which

 *

 *	This call sets the internal irqchip state of an interrupt,

 *	depending on the value of @which.

 * This call sets the internal irqchip state of an interrupt, depending on

 * the value of @which.

 *

 *	This function should be called with migration disabled if the

 *	interrupt controller has per-cpu registers.

 * This function should be called with migration disabled if the interrupt

 * controller has per-cpu registers.

 */

int irq_set_irqchip_state(unsigned int irq, enum irqchip_irq_state which,

			  bool val)

int irq_set_irqchip_state(unsigned int irq, enum irqchip_irq_state which, bool val)

{

	struct irq_desc *desc;

	struct irq_data *data;