Commit 923ff76e authored by Slava Abramov's avatar Slava Abramov Committed by Alex Deucher

drm/amdgpu: update documentation for amdgpu_irq.c v3

Add/update function level documentation and add reference to amdgpu_irq.c
in amdgpu.rst

v2:
Added DOC comment
Added more explanations for amdgpu_hotplug_work_func
Properly formatted unused parameters
Properly formatted return values
Fixed usage of acronyms
More consistent styling

v3:
Removed duplicate "not"
Using '&' to refer to functions and types
Signed-off-by: default avatarSlava Abramov <slava.abramov@amd.com>
Acked-by: default avatarChristian König <christian.koenig@amd.com>
Reviewed-by: default avatarMichel Dänzer <michel.daenzer@amd.com>
Signed-off-by: default avatarAlex Deucher <alexander.deucher@amd.com>
parent 7fc48e59
...@@ -52,4 +52,12 @@ AMDGPU Virtual Memory ...@@ -52,4 +52,12 @@ AMDGPU Virtual Memory
:doc: GPUVM :doc: GPUVM
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c .. 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: :internal:
...@@ -25,6 +25,23 @@ ...@@ -25,6 +25,23 @@
* Alex Deucher * Alex Deucher
* Jerome Glisse * 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 <linux/irq.h>
#include <drm/drmP.h> #include <drm/drmP.h>
#include <drm/drm_crtc_helper.h> #include <drm/drm_crtc_helper.h>
...@@ -43,19 +60,21 @@ ...@@ -43,19 +60,21 @@
#define AMDGPU_WAIT_IDLE_TIMEOUT 200 #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). * This is the hotplug event work handler (all ASICs).
* The work gets scheduled from the irq handler if there * The work gets scheduled from the IRQ handler if there
* was a hot plug interrupt. It walks the connector table * was a hotplug interrupt. It walks through the connector table
* and calls the hotplug handler for each one, then sends * and calls hotplug handler for each connector. After this, it sends
* a drm hotplug event to alert userspace. * 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) static void amdgpu_hotplug_work_func(struct work_struct *work)
{ {
...@@ -74,13 +93,12 @@ static void amdgpu_hotplug_work_func(struct work_struct *work) ...@@ -74,13 +93,12 @@ 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+). * Execute scheduled GPU reset (Cayman+).
* This function is called when the irq handler * This function is called when the IRQ handler thinks we need a GPU reset.
* thinks we need a gpu reset.
*/ */
static void amdgpu_irq_reset_work_func(struct work_struct *work) static void amdgpu_irq_reset_work_func(struct work_struct *work)
{ {
...@@ -91,7 +109,13 @@ static void amdgpu_irq_reset_work_func(struct work_struct *work) ...@@ -91,7 +109,13 @@ static void amdgpu_irq_reset_work_func(struct work_struct *work)
amdgpu_device_gpu_recover(adev, NULL, false); 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) void amdgpu_irq_disable_all(struct amdgpu_device *adev)
{ {
unsigned long irqflags; unsigned long irqflags;
...@@ -123,11 +147,15 @@ void amdgpu_irq_disable_all(struct amdgpu_device *adev) ...@@ -123,11 +147,15 @@ void amdgpu_irq_disable_all(struct amdgpu_device *adev)
} }
/** /**
* 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) irqreturn_t amdgpu_irq_handler(int irq, void *arg)
{ {
...@@ -142,18 +170,18 @@ irqreturn_t amdgpu_irq_handler(int irq, void *arg) ...@@ -142,18 +170,18 @@ 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 * Returns:
* MSIs should be enabled on a particular chip (all asics). * *true* if MSIs are allowed to be enabled or *false* otherwise
* Returns true if MSIs should be enabled, false if MSIs
* should not be enabled.
*/ */
static bool amdgpu_msi_ok(struct amdgpu_device *adev) static bool amdgpu_msi_ok(struct amdgpu_device *adev)
{ {
/* force MSI on */
if (amdgpu_msi == 1) if (amdgpu_msi == 1)
return true; return true;
else if (amdgpu_msi == 0) else if (amdgpu_msi == 0)
...@@ -163,12 +191,15 @@ static bool amdgpu_msi_ok(struct amdgpu_device *adev) ...@@ -163,12 +191,15 @@ static bool amdgpu_msi_ok(struct amdgpu_device *adev)
} }
/** /**
* amdgpu_irq_init - init driver interrupt info * amdgpu_irq_init - initialize interrupt handling
* *
* @adev: amdgpu device pointer * @adev: amdgpu device pointer
* *
* Sets up the work irq handlers, vblank init, MSIs, etc. (all asics). * Sets up work functions for hotplug and reset interrupts, enables MSI
* Returns 0 for success, error for failure. * 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) int amdgpu_irq_init(struct amdgpu_device *adev)
{ {
...@@ -176,7 +207,7 @@ int amdgpu_irq_init(struct amdgpu_device *adev) ...@@ -176,7 +207,7 @@ int amdgpu_irq_init(struct amdgpu_device *adev)
spin_lock_init(&adev->irq.lock); spin_lock_init(&adev->irq.lock);
/* enable msi */ /* Enable MSI if not disabled by module parameter */
adev->irq.msi_enabled = false; adev->irq.msi_enabled = false;
if (amdgpu_msi_ok(adev)) { if (amdgpu_msi_ok(adev)) {
...@@ -189,7 +220,7 @@ int amdgpu_irq_init(struct amdgpu_device *adev) ...@@ -189,7 +220,7 @@ int amdgpu_irq_init(struct amdgpu_device *adev)
if (!amdgpu_device_has_dc_support(adev)) { if (!amdgpu_device_has_dc_support(adev)) {
if (!adev->enable_virtual_display) 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? */ /* XXX: can this be enabled for DC? */
adev->ddev->vblank_disable_immediate = true; adev->ddev->vblank_disable_immediate = true;
...@@ -197,7 +228,7 @@ int amdgpu_irq_init(struct amdgpu_device *adev) ...@@ -197,7 +228,7 @@ int amdgpu_irq_init(struct amdgpu_device *adev)
if (r) if (r)
return r; return r;
/* pre DCE11 */ /* Pre-DCE11 */
INIT_WORK(&adev->hotplug_work, INIT_WORK(&adev->hotplug_work,
amdgpu_hotplug_work_func); amdgpu_hotplug_work_func);
} }
...@@ -220,11 +251,13 @@ int amdgpu_irq_init(struct amdgpu_device *adev) ...@@ -220,11 +251,13 @@ int amdgpu_irq_init(struct amdgpu_device *adev)
} }
/** /**
* amdgpu_irq_fini - tear down driver interrupt info * amdgpu_irq_fini - shut down interrupt handling
* *
* @adev: amdgpu device pointer * @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) void amdgpu_irq_fini(struct amdgpu_device *adev)
{ {
...@@ -264,12 +297,17 @@ void amdgpu_irq_fini(struct amdgpu_device *adev) ...@@ -264,12 +297,17 @@ 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 * @adev: amdgpu device pointer
* @src_id: source id for this source * @client_id: client id
* @source: irq source * @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, int amdgpu_irq_add_id(struct amdgpu_device *adev,
unsigned client_id, unsigned src_id, unsigned client_id, unsigned src_id,
...@@ -312,12 +350,12 @@ int amdgpu_irq_add_id(struct amdgpu_device *adev, ...@@ -312,12 +350,12 @@ int amdgpu_irq_add_id(struct amdgpu_device *adev,
} }
/** /**
* amdgpu_irq_dispatch - dispatch irq to IP blocks * amdgpu_irq_dispatch - dispatch IRQ to IP blocks
* *
* @adev: amdgpu device pointer * @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, void amdgpu_irq_dispatch(struct amdgpu_device *adev,
struct amdgpu_iv_entry *entry) struct amdgpu_iv_entry *entry)
...@@ -361,13 +399,13 @@ void amdgpu_irq_dispatch(struct amdgpu_device *adev, ...@@ -361,13 +399,13 @@ void amdgpu_irq_dispatch(struct amdgpu_device *adev,
} }
/** /**
* amdgpu_irq_update - update hw interrupt state * amdgpu_irq_update - update hardware interrupt state
* *
* @adev: amdgpu device pointer * @adev: amdgpu device pointer
* @src: interrupt src you want to enable * @src: interrupt source pointer
* @type: type of interrupt you want to update * @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, int amdgpu_irq_update(struct amdgpu_device *adev,
struct amdgpu_irq_src *src, unsigned type) struct amdgpu_irq_src *src, unsigned type)
...@@ -378,7 +416,7 @@ int amdgpu_irq_update(struct amdgpu_device *adev, ...@@ -378,7 +416,7 @@ int amdgpu_irq_update(struct amdgpu_device *adev,
spin_lock_irqsave(&adev->irq.lock, irqflags); 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 */ we might disable just enabled interrupts again */
if (amdgpu_irq_enabled(adev, src, type)) if (amdgpu_irq_enabled(adev, src, type))
state = AMDGPU_IRQ_STATE_ENABLE; state = AMDGPU_IRQ_STATE_ENABLE;
...@@ -390,6 +428,14 @@ int amdgpu_irq_update(struct amdgpu_device *adev, ...@@ -390,6 +428,14 @@ int amdgpu_irq_update(struct amdgpu_device *adev,
return r; 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) void amdgpu_irq_gpu_reset_resume_helper(struct amdgpu_device *adev)
{ {
int i, j, k; int i, j, k;
...@@ -413,10 +459,13 @@ void amdgpu_irq_gpu_reset_resume_helper(struct amdgpu_device *adev) ...@@ -413,10 +459,13 @@ void amdgpu_irq_gpu_reset_resume_helper(struct amdgpu_device *adev)
* amdgpu_irq_get - enable interrupt * amdgpu_irq_get - enable interrupt
* *
* @adev: amdgpu device pointer * @adev: amdgpu device pointer
* @src: interrupt src you want to enable * @src: interrupt source pointer
* @type: type of interrupt you want to enable * @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, int amdgpu_irq_get(struct amdgpu_device *adev, struct amdgpu_irq_src *src,
unsigned type) unsigned type)
...@@ -440,10 +489,13 @@ int amdgpu_irq_get(struct amdgpu_device *adev, struct amdgpu_irq_src *src, ...@@ -440,10 +489,13 @@ int amdgpu_irq_get(struct amdgpu_device *adev, struct amdgpu_irq_src *src,
* amdgpu_irq_put - disable interrupt * amdgpu_irq_put - disable interrupt
* *
* @adev: amdgpu device pointer * @adev: amdgpu device pointer
* @src: interrupt src you want to disable * @src: interrupt source pointer
* @type: type of interrupt you want to disable * @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, int amdgpu_irq_put(struct amdgpu_device *adev, struct amdgpu_irq_src *src,
unsigned type) unsigned type)
...@@ -464,12 +516,17 @@ int amdgpu_irq_put(struct amdgpu_device *adev, struct amdgpu_irq_src *src, ...@@ -464,12 +516,17 @@ int amdgpu_irq_put(struct amdgpu_device *adev, struct amdgpu_irq_src *src,
} }
/** /**
* amdgpu_irq_enabled - test if irq is enabled or not * amdgpu_irq_enabled - check whether interrupt is enabled or not
* *
* @adev: amdgpu device pointer * @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, bool amdgpu_irq_enabled(struct amdgpu_device *adev, struct amdgpu_irq_src *src,
unsigned type) unsigned type)
...@@ -486,7 +543,7 @@ bool amdgpu_irq_enabled(struct amdgpu_device *adev, struct amdgpu_irq_src *src, ...@@ -486,7 +543,7 @@ bool amdgpu_irq_enabled(struct amdgpu_device *adev, struct amdgpu_irq_src *src,
return !!atomic_read(&src->enabled_types[type]); return !!atomic_read(&src->enabled_types[type]);
} }
/* gen irq */ /* XXX: Generic IRQ handling */
static void amdgpu_irq_mask(struct irq_data *irqd) static void amdgpu_irq_mask(struct irq_data *irqd)
{ {
/* XXX */ /* XXX */
...@@ -497,12 +554,26 @@ static void amdgpu_irq_unmask(struct irq_data *irqd) ...@@ -497,12 +554,26 @@ static void amdgpu_irq_unmask(struct irq_data *irqd)
/* XXX */ /* XXX */
} }
/* amdgpu hardware interrupt chip descriptor */
static struct irq_chip amdgpu_irq_chip = { static struct irq_chip amdgpu_irq_chip = {
.name = "amdgpu-ih", .name = "amdgpu-ih",
.irq_mask = amdgpu_irq_mask, .irq_mask = amdgpu_irq_mask,
.irq_unmask = amdgpu_irq_unmask, .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, static int amdgpu_irqdomain_map(struct irq_domain *d,
unsigned int irq, irq_hw_number_t hwirq) unsigned int irq, irq_hw_number_t hwirq)
{ {
...@@ -514,17 +585,21 @@ static int amdgpu_irqdomain_map(struct irq_domain *d, ...@@ -514,17 +585,21 @@ static int amdgpu_irqdomain_map(struct irq_domain *d,
return 0; return 0;
} }
/* Implementation of methods for amdgpu IRQ domain */
static const struct irq_domain_ops amdgpu_hw_irqdomain_ops = { static const struct irq_domain_ops amdgpu_hw_irqdomain_ops = {
.map = amdgpu_irqdomain_map, .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 * @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). * 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) int amdgpu_irq_add_domain(struct amdgpu_device *adev)
{ {
...@@ -539,11 +614,11 @@ int amdgpu_irq_add_domain(struct amdgpu_device *adev) ...@@ -539,11 +614,11 @@ 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 * @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). * that may be driven by another driver (e.g., ACP).
*/ */
void amdgpu_irq_remove_domain(struct amdgpu_device *adev) void amdgpu_irq_remove_domain(struct amdgpu_device *adev)
...@@ -555,16 +630,17 @@ void amdgpu_irq_remove_domain(struct amdgpu_device *adev) ...@@ -555,16 +630,17 @@ void amdgpu_irq_remove_domain(struct amdgpu_device *adev)
} }
/** /**
* amdgpu_irq_create_mapping - create a mapping between a domain irq and a * amdgpu_irq_create_mapping - create mapping between domain Linux IRQs
* Linux irq
* *
* @adev: amdgpu device pointer * @adev: amdgpu device pointer
* @src_id: IH source id * @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 * Use this for components that generate a GPU interrupt, but are driven
* by a different driver (e.g., ACP). * 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) unsigned amdgpu_irq_create_mapping(struct amdgpu_device *adev, unsigned src_id)
{ {
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment