[PATCH v2] drm: Improve manual IRQ installation documentation
Daniel Vetter
daniel at ffwll.ch
Mon Jun 24 00:38:16 PDT 2013
On Sat, Jun 22, 2013 at 02:10:59PM +0200, Laurent Pinchart wrote:
> Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas at 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 at 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
More information about the dri-devel
mailing list