drm/amdgpu: update documentation for amdgpu_irq.c v3

   :doc: GPUVM

.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c

Interrupt Handling

------------------

.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c

   :doc: Interrupt Handling

.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c

   :internal:

 *          Alex Deucher

 *          Jerome Glisse

 */

/**

 * DOC: Interrupt Handling

 *

 * Interrupts generated within GPU hardware raise interrupt requests that are

 * passed to amdgpu IRQ handler which is responsible for detecting source and

 * type of the interrupt and dispatching matching handlers. If handling an

 * interrupt requires calling kernel functions that may sleep processing is

 * dispatched to work handlers.

 *

 * If MSI functionality is not disabled by module parameter then MSI

 * support will be enabled.

 *

 * For GPU interrupt sources that may be driven by another driver, IRQ domain

 * support is used (with mapping between virtual and hardware IRQs).

 */

#include <linux/irq.h>

#include <drm/drmP.h>

#include <drm/drm_crtc_helper.h>

#define AMDGPU_WAIT_IDLE_TIMEOUT 200

/*

 * Handle hotplug events outside the interrupt handler proper.

 */

/**

 * amdgpu_hotplug_work_func - display hotplug work handler

 * amdgpu_hotplug_work_func - work handler for display hotplug event

 *

 * @work: work struct

 * @work: work struct pointer

 *

 * This is the hot plug event work handler (all asics).

 * The work gets scheduled from the irq handler if there

 * was a hot plug interrupt.  It walks the connector table

 * and calls the hotplug handler for each one, then sends

 * a drm hotplug event to alert userspace.

 * This is the hotplug event work handler (all ASICs).

 * The work gets scheduled from the IRQ handler if there

 * was a hotplug interrupt.  It walks through the connector table

 * and calls hotplug handler for each connector. After this, it sends

 * a DRM hotplug event to alert userspace.

 *

 * This design approach is required in order to defer hotplug event handling

 * from the IRQ handler to a work handler because hotplug handler has to use

 * mutexes which cannot be locked in an IRQ handler (since &mutex_lock may

 * sleep).

 */

static void amdgpu_hotplug_work_func(struct work_struct *work)

{

}

/**

 * amdgpu_irq_reset_work_func - execute gpu reset

 * amdgpu_irq_reset_work_func - execute GPU reset

 *

 * @work: work struct

 * @work: work struct pointer

 *

 * Execute scheduled gpu reset (cayman+).

 * This function is called when the irq handler

 * thinks we need a gpu reset.

 * Execute scheduled GPU reset (Cayman+).

 * This function is called when the IRQ handler thinks we need a GPU reset.

 */

static void amdgpu_irq_reset_work_func(struct work_struct *work)

{

		amdgpu_device_gpu_recover(adev, NULL, false);

}

/* Disable *all* interrupts */

/**

 * amdgpu_irq_disable_all - disable *all* interrupts

 *

 * @adev: amdgpu device pointer

 *

 * Disable all types of interrupts from all sources.

 */

void amdgpu_irq_disable_all(struct amdgpu_device *adev)

{

	unsigned long irqflags;

}

/**

 * amdgpu_irq_handler - irq handler

 * amdgpu_irq_handler - IRQ handler

 *

 * @irq: IRQ number (unused)

 * @arg: pointer to DRM device

 *

 * @int irq, void *arg: args

 * IRQ handler for amdgpu driver (all ASICs).

 *

 * This is the irq handler for the amdgpu driver (all asics).

 * Returns:

 * result of handling the IRQ, as defined by &irqreturn_t

 */

irqreturn_t amdgpu_irq_handler(int irq, void *arg)

{

}

/**

 * amdgpu_msi_ok - asic specific msi checks

 * amdgpu_msi_ok - check whether MSI functionality is enabled

 *

 * @adev: amdgpu device pointer

 * @adev: amdgpu device pointer (unused)

 *

 * Checks whether MSI functionality has been disabled via module parameter

 * (all ASICs).

 *

 * Handles asic specific MSI checks to determine if

 * MSIs should be enabled on a particular chip (all asics).

 * Returns true if MSIs should be enabled, false if MSIs

 * should not be enabled.

 * Returns:

 * *true* if MSIs are allowed to be enabled or *false* otherwise

 */

static bool amdgpu_msi_ok(struct amdgpu_device *adev)

{

	/* force MSI on */

	if (amdgpu_msi == 1)

		return true;

	else if (amdgpu_msi == 0)

}

/**

 * amdgpu_irq_init - init driver interrupt info

 * amdgpu_irq_init - initialize interrupt handling

 *

 * @adev: amdgpu device pointer

 *

 * Sets up the work irq handlers, vblank init, MSIs, etc. (all asics).

 * Returns 0 for success, error for failure.

 * Sets up work functions for hotplug and reset interrupts, enables MSI

 * functionality, initializes vblank, hotplug and reset interrupt handling.

 *

 * Returns:

 * 0 on success or error code on failure

 */

int amdgpu_irq_init(struct amdgpu_device *adev)

{

	spin_lock_init(&adev->irq.lock);

	/* enable msi */

	/* Enable MSI if not disabled by module parameter */

	adev->irq.msi_enabled = false;

	if (amdgpu_msi_ok(adev)) {

	if (!amdgpu_device_has_dc_support(adev)) {

		if (!adev->enable_virtual_display)

			/* Disable vblank irqs aggressively for power-saving */

			/* Disable vblank IRQs aggressively for power-saving */

			/* XXX: can this be enabled for DC? */

			adev->ddev->vblank_disable_immediate = true;

		if (r)

			return r;

		/* pre DCE11 */

		/* Pre-DCE11 */

		INIT_WORK(&adev->hotplug_work,

				amdgpu_hotplug_work_func);

	}

}

/**

 * amdgpu_irq_fini - tear down driver interrupt info

 * amdgpu_irq_fini - shut down interrupt handling

 *

 * @adev: amdgpu device pointer

 *

 * Tears down the work irq handlers, vblank handlers, MSIs, etc. (all asics).

 * Tears down work functions for hotplug and reset interrupts, disables MSI

 * functionality, shuts down vblank, hotplug and reset interrupt handling,

 * turns off interrupts from all sources (all ASICs).

 */

void amdgpu_irq_fini(struct amdgpu_device *adev)

{

}

/**

 * amdgpu_irq_add_id - register irq source

 * amdgpu_irq_add_id - register IRQ source

 *

 * @adev: amdgpu device pointer

 * @src_id: source id for this source

 * @source: irq source

 * @client_id: client id

 * @src_id: source id

 * @source: IRQ source pointer

 *

 * Registers IRQ source on a client.

 *

 * Returns:

 * 0 on success or error code otherwise

 */

int amdgpu_irq_add_id(struct amdgpu_device *adev,

		      unsigned client_id, unsigned src_id,

}

/**

 * amdgpu_irq_dispatch - dispatch irq to IP blocks

 * amdgpu_irq_dispatch - dispatch IRQ to IP blocks

 *

 * @adev: amdgpu device pointer

 * @entry: interrupt vector

 * @entry: interrupt vector pointer

 *

 * Dispatches the irq to the different IP blocks

 * Dispatches IRQ to IP blocks.

 */

void amdgpu_irq_dispatch(struct amdgpu_device *adev,

			 struct amdgpu_iv_entry *entry)

}

/**

 * amdgpu_irq_update - update hw interrupt state

 * amdgpu_irq_update - update hardware interrupt state

 *

 * @adev: amdgpu device pointer

 * @src: interrupt src you want to enable

 * @type: type of interrupt you want to update

 * @src: interrupt source pointer

 * @type: type of interrupt

 *

 * Updates the interrupt state for a specific src (all asics).

 * Updates interrupt state for the specific source (all ASICs).

 */

int amdgpu_irq_update(struct amdgpu_device *adev,

			     struct amdgpu_irq_src *src, unsigned type)

	spin_lock_irqsave(&adev->irq.lock, irqflags);

	/* we need to determine after taking the lock, otherwise

	/* We need to determine after taking the lock, otherwise

	   we might disable just enabled interrupts again */

	if (amdgpu_irq_enabled(adev, src, type))

		state = AMDGPU_IRQ_STATE_ENABLE;

	return r;

}

/**

 * amdgpu_irq_gpu_reset_resume_helper - update interrupt states on all sources

 *

 * @adev: amdgpu device pointer

 *

 * Updates state of all types of interrupts on all sources on resume after

 * reset.

 */

void amdgpu_irq_gpu_reset_resume_helper(struct amdgpu_device *adev)

{

	int i, j, k;

 * amdgpu_irq_get - enable interrupt

 *

 * @adev: amdgpu device pointer

 * @src: interrupt src you want to enable

 * @type: type of interrupt you want to enable

 * @src: interrupt source pointer

 * @type: type of interrupt

 *

 * Enables the interrupt type for a specific src (all asics).

 * Enables specified type of interrupt on the specified source (all ASICs).

 *

 * Returns:

 * 0 on success or error code otherwise

 */

int amdgpu_irq_get(struct amdgpu_device *adev, struct amdgpu_irq_src *src,

		   unsigned type)

 * amdgpu_irq_put - disable interrupt

 *

 * @adev: amdgpu device pointer

 * @src: interrupt src you want to disable

 * @type: type of interrupt you want to disable

 * @src: interrupt source pointer

 * @type: type of interrupt

 *

 * Enables specified type of interrupt on the specified source (all ASICs).

 *

 * Disables the interrupt type for a specific src (all asics).

 * Returns:

 * 0 on success or error code otherwise

 */

int amdgpu_irq_put(struct amdgpu_device *adev, struct amdgpu_irq_src *src,

		   unsigned type)

}

/**

 * amdgpu_irq_enabled - test if irq is enabled or not

 * amdgpu_irq_enabled - check whether interrupt is enabled or not

 *

 * @adev: amdgpu device pointer

 * @idx: interrupt src you want to test

 * @src: interrupt source pointer

 * @type: type of interrupt

 *

 * Tests if the given interrupt source is enabled or not

 * Checks whether the given type of interrupt is enabled on the given source.

 *

 * Returns:

 * *true* if interrupt is enabled, *false* if interrupt is disabled or on

 * invalid parameters

 */

bool amdgpu_irq_enabled(struct amdgpu_device *adev, struct amdgpu_irq_src *src,

			unsigned type)

	return !!atomic_read(&src->enabled_types[type]);

}

/* gen irq */

/* XXX: Generic IRQ handling */

static void amdgpu_irq_mask(struct irq_data *irqd)

{

	/* XXX */

	/* XXX */

}

/* amdgpu hardware interrupt chip descriptor */

static struct irq_chip amdgpu_irq_chip = {

	.name = "amdgpu-ih",

	.irq_mask = amdgpu_irq_mask,

	.irq_unmask = amdgpu_irq_unmask,

};

/**

 * amdgpu_irqdomain_map - create mapping between virtual and hardware IRQ numbers

 *

 * @d: amdgpu IRQ domain pointer (unused)

 * @irq: virtual IRQ number

 * @hwirq: hardware irq number

 *

 * Current implementation assigns simple interrupt handler to the given virtual

 * IRQ.

 *

 * Returns:

 * 0 on success or error code otherwise

 */

static int amdgpu_irqdomain_map(struct irq_domain *d,

				unsigned int irq, irq_hw_number_t hwirq)

{

	return 0;

}

/* Implementation of methods for amdgpu IRQ domain */

static const struct irq_domain_ops amdgpu_hw_irqdomain_ops = {

	.map = amdgpu_irqdomain_map,

};

/**

 * amdgpu_irq_add_domain - create a linear irq domain

 * amdgpu_irq_add_domain - create a linear IRQ domain

 *

 * @adev: amdgpu device pointer

 *

 * Create an irq domain for GPU interrupt sources

 * Creates an IRQ domain for GPU interrupt sources

 * that may be driven by another driver (e.g., ACP).

 *

 * Returns:

 * 0 on success or error code otherwise

 */

int amdgpu_irq_add_domain(struct amdgpu_device *adev)

{

}

/**

 * amdgpu_irq_remove_domain - remove the irq domain

 * amdgpu_irq_remove_domain - remove the IRQ domain

 *

 * @adev: amdgpu device pointer

 *

 * Remove the irq domain for GPU interrupt sources

 * Removes the IRQ domain for GPU interrupt sources

 * that may be driven by another driver (e.g., ACP).

 */

void amdgpu_irq_remove_domain(struct amdgpu_device *adev)

}

/**

 * amdgpu_irq_create_mapping - create a mapping between a domain irq and a

 *                             Linux irq

 * amdgpu_irq_create_mapping - create mapping between domain Linux IRQs

 *

 * @adev: amdgpu device pointer

 * @src_id: IH source id

 *

 * Create a mapping between a domain irq (GPU IH src id) and a Linux irq

 * Creates mapping between a domain IRQ (GPU IH src id) and a Linux IRQ

 * Use this for components that generate a GPU interrupt, but are driven

 * by a different driver (e.g., ACP).

 * Returns the Linux irq.

 *

 * Returns:

 * Linux IRQ

 */

unsigned amdgpu_irq_create_mapping(struct amdgpu_device *adev, unsigned src_id)

{