Commit 02b62985 authored by Laurent Pinchart's avatar Laurent Pinchart Committed by Dave Airlie
Browse files

drm: Improve manual IRQ installation documentation 



Define the rules for using irqs from drm drivers.

Signed-off-by: default avatarLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Reviewed-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: default avatarDave Airlie <airlied@redhat.com>
parent da34242e

Documentation/DocBook/drm.tmpl

+70 −48
Original line number Diff line number Diff line
@@ -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 &amp;

              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 &amp; handler

              support shared IRQs (note that this is required of PCI  drivers).

            </para></listitem>

          </varlistentry>

          <varlistentry>
@@ -344,15 +345,18 @@ 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.

          support a single interrupt per device, devices that use more than one

          IRQs need to be handled manually.

        </para>

  <!--!Fdrivers/char/drm/drm_irq.c drm_irq_install-->

        <sect4>

          <title>Managed IRQ Registration</title>

          <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.

            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
@@ -388,6 +392,24 @@ char *date;</synopsis> 
            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>