* [PATCH v2] drm: Improve manual IRQ installation documentation
@ 2013-06-22 12:10 Laurent Pinchart
2013-06-24 7:38 ` Daniel Vetter
0 siblings, 1 reply; 2+ messages in thread
From: Laurent Pinchart @ 2013-06-22 12:10 UTC (permalink / raw)
To: dri-devel
Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
---
Documentation/DocBook/drm.tmpl | 118 ++++++++++++++++++++++++-----------------
1 file changed, 70 insertions(+), 48 deletions(-)
Changes since v1:
- Document manual IRQ registration
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 91ee107..a608094 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -186,11 +186,12 @@
<varlistentry>
<term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term>
<listitem><para>
- DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler. The
- DRM core will automatically register an interrupt handler when the
- flag is set. DRIVER_IRQ_SHARED indicates whether the device &
- handler support shared IRQs (note that this is required of PCI
- drivers).
+ DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler
+ managed by the DRM Core. The core will support simple IRQ handler
+ installation when the flag is set. The installation process is
+ described in <xref linkend="drm-irq-registration"/>.</para>
+ <para>DRIVER_IRQ_SHARED indicates whether the device & handler
+ support shared IRQs (note that this is required of PCI drivers).
</para></listitem>
</varlistentry>
<varlistentry>
@@ -344,50 +345,71 @@ char *date;</synopsis>
The DRM core tries to facilitate IRQ handler registration and
unregistration by providing <function>drm_irq_install</function> and
<function>drm_irq_uninstall</function> functions. Those functions only
- support a single interrupt per device.
- </para>
- <!--!Fdrivers/char/drm/drm_irq.c drm_irq_install-->
- <para>
- Both functions get the device IRQ by calling
- <function>drm_dev_to_irq</function>. This inline function will call a
- bus-specific operation to retrieve the IRQ number. For platform devices,
- <function>platform_get_irq</function>(..., 0) is used to retrieve the
- IRQ number.
- </para>
- <para>
- <function>drm_irq_install</function> starts by calling the
- <methodname>irq_preinstall</methodname> driver operation. The operation
- is optional and must make sure that the interrupt will not get fired by
- clearing all pending interrupt flags or disabling the interrupt.
- </para>
- <para>
- The IRQ will then be requested by a call to
- <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver
- feature flag is set, a shared (IRQF_SHARED) IRQ handler will be
- requested.
- </para>
- <para>
- The IRQ handler function must be provided as the mandatory irq_handler
- driver operation. It will get passed directly to
- <function>request_irq</function> and thus has the same prototype as all
- IRQ handlers. It will get called with a pointer to the DRM device as the
- second argument.
- </para>
- <para>
- Finally the function calls the optional
- <methodname>irq_postinstall</methodname> driver operation. The operation
- usually enables interrupts (excluding the vblank interrupt, which is
- enabled separately), but drivers may choose to enable/disable interrupts
- at a different time.
- </para>
- <para>
- <function>drm_irq_uninstall</function> is similarly used to uninstall an
- IRQ handler. It starts by waking up all processes waiting on a vblank
- interrupt to make sure they don't hang, and then calls the optional
- <methodname>irq_uninstall</methodname> driver operation. The operation
- must disable all hardware interrupts. Finally the function frees the IRQ
- by calling <function>free_irq</function>.
+ support a single interrupt per device, devices that use more than one
+ IRQs need to be handled manually.
</para>
+ <sect4>
+ <title>Managed IRQ Registration</title>
+ <para>
+ Both the <function>drm_irq_install</function> and
+ <function>drm_irq_uninstall</function> functions get the device IRQ by
+ calling <function>drm_dev_to_irq</function>. This inline function will
+ call a bus-specific operation to retrieve the IRQ number. For platform
+ devices, <function>platform_get_irq</function>(..., 0) is used to
+ retrieve the IRQ number.
+ </para>
+ <para>
+ <function>drm_irq_install</function> starts by calling the
+ <methodname>irq_preinstall</methodname> driver operation. The operation
+ is optional and must make sure that the interrupt will not get fired by
+ clearing all pending interrupt flags or disabling the interrupt.
+ </para>
+ <para>
+ The IRQ will then be requested by a call to
+ <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver
+ feature flag is set, a shared (IRQF_SHARED) IRQ handler will be
+ requested.
+ </para>
+ <para>
+ The IRQ handler function must be provided as the mandatory irq_handler
+ driver operation. It will get passed directly to
+ <function>request_irq</function> and thus has the same prototype as all
+ IRQ handlers. It will get called with a pointer to the DRM device as the
+ second argument.
+ </para>
+ <para>
+ Finally the function calls the optional
+ <methodname>irq_postinstall</methodname> driver operation. The operation
+ usually enables interrupts (excluding the vblank interrupt, which is
+ enabled separately), but drivers may choose to enable/disable interrupts
+ at a different time.
+ </para>
+ <para>
+ <function>drm_irq_uninstall</function> is similarly used to uninstall an
+ IRQ handler. It starts by waking up all processes waiting on a vblank
+ interrupt to make sure they don't hang, and then calls the optional
+ <methodname>irq_uninstall</methodname> driver operation. The operation
+ must disable all hardware interrupts. Finally the function frees the IRQ
+ by calling <function>free_irq</function>.
+ </para>
+ </sect4>
+ <sect4>
+ <title>Manual IRQ Registration</title>
+ <para>
+ Drivers that require multiple interrupt handlers can't use the managed
+ IRQ registration functions. In that case IRQs must be registered and
+ unregistered manually (usually with the <function>request_irq</function>
+ and <function>free_irq</function> functions, or their devm_* equivalent).
+ </para>
+ <para>
+ When manually registering IRQs, drivers must not set the DRIVER_HAVE_IRQ
+ driver feature flag, and must not provide the
+ <methodname>irq_handler</methodname> driver operation. They must set the
+ <structname>drm_device</structname> <structfield>irq_enabled</structfield>
+ field to 1 upon registration of the IRQs, and clear it to 0 after
+ unregistering the IRQs.
+ </para>
+ </sect4>
</sect3>
<sect3>
<title>Memory Manager Initialization</title>
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH v2] drm: Improve manual IRQ installation documentation
2013-06-22 12:10 [PATCH v2] drm: Improve manual IRQ installation documentation Laurent Pinchart
@ 2013-06-24 7:38 ` Daniel Vetter
0 siblings, 0 replies; 2+ messages in thread
From: Daniel Vetter @ 2013-06-24 7:38 UTC (permalink / raw)
To: Laurent Pinchart; +Cc: dri-devel
On Sat, Jun 22, 2013 at 02:10:59PM +0200, Laurent Pinchart wrote:
> Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Hm, a bit a thin commit message, but changes look good. So with the commit
message patched up this is
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> ---
> Documentation/DocBook/drm.tmpl | 118 ++++++++++++++++++++++++-----------------
> 1 file changed, 70 insertions(+), 48 deletions(-)
>
> Changes since v1:
>
> - Document manual IRQ registration
>
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 91ee107..a608094 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -186,11 +186,12 @@
> <varlistentry>
> <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term>
> <listitem><para>
> - DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler. The
> - DRM core will automatically register an interrupt handler when the
> - flag is set. DRIVER_IRQ_SHARED indicates whether the device &
> - handler support shared IRQs (note that this is required of PCI
> - drivers).
> + DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler
> + managed by the DRM Core. The core will support simple IRQ handler
> + installation when the flag is set. The installation process is
> + described in <xref linkend="drm-irq-registration"/>.</para>
> + <para>DRIVER_IRQ_SHARED indicates whether the device & handler
> + support shared IRQs (note that this is required of PCI drivers).
> </para></listitem>
> </varlistentry>
> <varlistentry>
> @@ -344,50 +345,71 @@ char *date;</synopsis>
> The DRM core tries to facilitate IRQ handler registration and
> unregistration by providing <function>drm_irq_install</function> and
> <function>drm_irq_uninstall</function> functions. Those functions only
> - support a single interrupt per device.
> - </para>
> - <!--!Fdrivers/char/drm/drm_irq.c drm_irq_install-->
> - <para>
> - Both functions get the device IRQ by calling
> - <function>drm_dev_to_irq</function>. This inline function will call a
> - bus-specific operation to retrieve the IRQ number. For platform devices,
> - <function>platform_get_irq</function>(..., 0) is used to retrieve the
> - IRQ number.
> - </para>
> - <para>
> - <function>drm_irq_install</function> starts by calling the
> - <methodname>irq_preinstall</methodname> driver operation. The operation
> - is optional and must make sure that the interrupt will not get fired by
> - clearing all pending interrupt flags or disabling the interrupt.
> - </para>
> - <para>
> - The IRQ will then be requested by a call to
> - <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver
> - feature flag is set, a shared (IRQF_SHARED) IRQ handler will be
> - requested.
> - </para>
> - <para>
> - The IRQ handler function must be provided as the mandatory irq_handler
> - driver operation. It will get passed directly to
> - <function>request_irq</function> and thus has the same prototype as all
> - IRQ handlers. It will get called with a pointer to the DRM device as the
> - second argument.
> - </para>
> - <para>
> - Finally the function calls the optional
> - <methodname>irq_postinstall</methodname> driver operation. The operation
> - usually enables interrupts (excluding the vblank interrupt, which is
> - enabled separately), but drivers may choose to enable/disable interrupts
> - at a different time.
> - </para>
> - <para>
> - <function>drm_irq_uninstall</function> is similarly used to uninstall an
> - IRQ handler. It starts by waking up all processes waiting on a vblank
> - interrupt to make sure they don't hang, and then calls the optional
> - <methodname>irq_uninstall</methodname> driver operation. The operation
> - must disable all hardware interrupts. Finally the function frees the IRQ
> - by calling <function>free_irq</function>.
> + support a single interrupt per device, devices that use more than one
> + IRQs need to be handled manually.
> </para>
> + <sect4>
> + <title>Managed IRQ Registration</title>
> + <para>
> + Both the <function>drm_irq_install</function> and
> + <function>drm_irq_uninstall</function> functions get the device IRQ by
> + calling <function>drm_dev_to_irq</function>. This inline function will
> + call a bus-specific operation to retrieve the IRQ number. For platform
> + devices, <function>platform_get_irq</function>(..., 0) is used to
> + retrieve the IRQ number.
> + </para>
> + <para>
> + <function>drm_irq_install</function> starts by calling the
> + <methodname>irq_preinstall</methodname> driver operation. The operation
> + is optional and must make sure that the interrupt will not get fired by
> + clearing all pending interrupt flags or disabling the interrupt.
> + </para>
> + <para>
> + The IRQ will then be requested by a call to
> + <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver
> + feature flag is set, a shared (IRQF_SHARED) IRQ handler will be
> + requested.
> + </para>
> + <para>
> + The IRQ handler function must be provided as the mandatory irq_handler
> + driver operation. It will get passed directly to
> + <function>request_irq</function> and thus has the same prototype as all
> + IRQ handlers. It will get called with a pointer to the DRM device as the
> + second argument.
> + </para>
> + <para>
> + Finally the function calls the optional
> + <methodname>irq_postinstall</methodname> driver operation. The operation
> + usually enables interrupts (excluding the vblank interrupt, which is
> + enabled separately), but drivers may choose to enable/disable interrupts
> + at a different time.
> + </para>
> + <para>
> + <function>drm_irq_uninstall</function> is similarly used to uninstall an
> + IRQ handler. It starts by waking up all processes waiting on a vblank
> + interrupt to make sure they don't hang, and then calls the optional
> + <methodname>irq_uninstall</methodname> driver operation. The operation
> + must disable all hardware interrupts. Finally the function frees the IRQ
> + by calling <function>free_irq</function>.
> + </para>
> + </sect4>
> + <sect4>
> + <title>Manual IRQ Registration</title>
> + <para>
> + Drivers that require multiple interrupt handlers can't use the managed
> + IRQ registration functions. In that case IRQs must be registered and
> + unregistered manually (usually with the <function>request_irq</function>
> + and <function>free_irq</function> functions, or their devm_* equivalent).
> + </para>
> + <para>
> + When manually registering IRQs, drivers must not set the DRIVER_HAVE_IRQ
> + driver feature flag, and must not provide the
> + <methodname>irq_handler</methodname> driver operation. They must set the
> + <structname>drm_device</structname> <structfield>irq_enabled</structfield>
> + field to 1 upon registration of the IRQs, and clear it to 0 after
> + unregistering the IRQs.
> + </para>
> + </sect4>
> </sect3>
> <sect3>
> <title>Memory Manager Initialization</title>
> --
> Regards,
>
> Laurent Pinchart
>
--
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2013-06-24 7:38 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-06-22 12:10 [PATCH v2] drm: Improve manual IRQ installation documentation Laurent Pinchart
2013-06-24 7:38 ` Daniel Vetter
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.