[Intel-gfx] [PATCH 09/14] drm/i915: kerneldoc for interrupt enable/disable functions

[Paulo Zanoni]

2014-09-30 5:56 GMT-03:00 Daniel Vetter <daniel.vetter at ffwll.ch>:
> Just start with the basics for now.
>
> Since there's a lot of different functionality in i915_irq.c I've
> decided to split it into different sections and pull in just the
> relevant functions. Splitting into different files looks like a lot
> more work since the interrupt handlers do an awful lot of reuse all
> over.
>

If you do the rename I suggested in patch 7, you'll have to change this patch.

Reviewed-by: Paulo Zanoni <paulo.r.zanoni at intel.com>

> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> ---
>  Documentation/DocBook/drm.tmpl  |  9 ++++++
>  drivers/gpu/drm/i915/i915_irq.c | 61 +++++++++++++++++++++++++++++++++++++++--
>  2 files changed, 68 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 69e422ab8352..e8ef0f9c7396 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -3798,6 +3798,14 @@ int num_ioctls;</synopsis>
>  !Pdrivers/gpu/drm/i915/intel_runtime_pm.c runtime pm
>  !Idrivers/gpu/drm/i915/intel_runtime_pm.c
>        </sect2>
> +      <sect2>
> +        <title>Interrupt Handling</title>
> +!Pdrivers/gpu/drm/i915/i915_irq.c interrupt handling
> +!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_init intel_irq_init_hw intel_hpd_init
> +!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_fini
> +!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_disable_interrupts
> +!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_enable_interrupts
> +      </sect2>
>      </sect1>
>      <sect1>
>        <title>Display Hardware Handling</title>
> @@ -3951,5 +3959,6 @@ int num_ioctls;</synopsis>
>        </sect2>
>      </sect1>
>    </chapter>
> +!Cdrivers/gpu/drm/i915/i915_irq.c
>  </part>
>  </book>
> diff --git a/drivers/gpu/drm/i915/i915_irq.c b/drivers/gpu/drm/i915/i915_irq.c
> index 2c436e6c55b0..039625c22be4 100644
> --- a/drivers/gpu/drm/i915/i915_irq.c
> +++ b/drivers/gpu/drm/i915/i915_irq.c
> @@ -37,6 +37,14 @@
>  #include "i915_trace.h"
>  #include "intel_drv.h"
>
> +/**
> + * DOC: interrupt handling
> + *
> + * These functions provide the basic support for enabling and disabling the
> + * interrupt handling support. There's a lot more functionality in i915_irq.c
> + * and related files, but that will be described in separate chapters.
> + */
> +
>  static const u32 hpd_ibx[] = {
>         [HPD_CRT] = SDE_CRT_HOTPLUG,
>         [HPD_SDVO_B] = SDE_SDVOB_HOTPLUG,
> @@ -4631,6 +4639,13 @@ static void intel_hpd_irq_reenable_work(struct work_struct *work)
>         intel_runtime_pm_put(dev_priv);
>  }
>
> +/**
> + * intel_irq_init - initializes irq support
> + * @dev_priv: i915 device instance
> + *
> + * This function initializes all the irq support including work items, timers
> + * and all the vtables. It does not setup the interrupt itself though.
> + */
>  void intel_irq_init(struct drm_i915_private *dev_priv)
>  {
>         struct drm_device *dev = dev_priv->dev;
> @@ -4736,6 +4751,18 @@ void intel_irq_init(struct drm_i915_private *dev_priv)
>         }
>  }
>
> +/**
> + * intel_hpd_init - initializes and enables hpd support
> + * @dev_priv: i915 device instance
> + *
> + * This function enables the hotplug support. It requires that interrupts have
> + * already been enabled with intel_irq_init_hw(). From this point on hotplug and
> + * poll request can run concurrently to other code, so locking rules must be
> + * obeyed.
> + *
> + * This is a separate step from interrupt enabling to simplify the locking rules
> + * in the driver load and resume code.
> + */
>  void intel_hpd_init(struct drm_i915_private *dev_priv)
>  {
>         struct drm_device *dev = dev_priv->dev;
> @@ -4764,6 +4791,17 @@ void intel_hpd_init(struct drm_i915_private *dev_priv)
>         spin_unlock_irq(&dev_priv->irq_lock);
>  }
>
> +/**
> + * intel_irq_init_hw - enables the hardware interrupt
> + * @dev_priv: i915 device instance
> + *
> + * This function enables the hardware interrupt handling, but leaves the hotplug
> + * handling still disabled. It is called after intel_irq_init().
> + *
> + * In the driver load and resume code we need working interrupts in a few places
> + * but don't want to deal with the hassle of concurrent probe and hotplug
> + * workers. Hence the split into this two-stage approach.
> + */
>  int intel_irq_init_hw(struct drm_i915_private *dev_priv)
>  {
>         /*
> @@ -4776,6 +4814,13 @@ int intel_irq_init_hw(struct drm_i915_private *dev_priv)
>         return drm_irq_install(dev_priv->dev, dev_priv->dev->pdev->irq);
>  }
>
> +/**
> + * intel_irq_fini - finilizes all irq handling
> + * @dev_priv: i915 device instance
> + *
> + * This stops interrupt and hotplug handling and unregisters and frees all
> + * resources acquired in the init functions.
> + */
>  void intel_irq_fini(struct drm_i915_private *dev_priv)
>  {
>         drm_irq_uninstall(dev_priv->dev);
> @@ -4783,14 +4828,26 @@ void intel_irq_fini(struct drm_i915_private *dev_priv)
>         dev_priv->pm.irqs_enabled = false;
>  }
>
> -/* Disable interrupts so we can allow runtime PM. */
> +/**
> + * intel_runtime_pm_disable_interrupts - runtime interrupt disabling
> + * @dev_priv: i915 device instance
> + *
> + * This function is used to disable interrupts at runtime, both in the runtime
> + * pm and the system suspend/resume code.
> + */
>  void intel_runtime_pm_disable_interrupts(struct drm_i915_private *dev_priv)
>  {
>         dev_priv->dev->driver->irq_uninstall(dev_priv->dev);
>         dev_priv->pm.irqs_enabled = false;
>  }
>
> -/* Restore interrupts so we can recover from runtime PM. */
> +/**
> + * intel_runtime_pm_enable_interrupts - runtime interrupt enabling
> + * @dev_priv: i915 device instance
> + *
> + * This function is used to enable interrupts at runtime, both in the runtime
> + * pm and the system suspend/resume code.
> + */
>  void intel_runtime_pm_enable_interrupts(struct drm_i915_private *dev_priv)
>  {
>         dev_priv->pm.irqs_enabled = true;
> --
> 2.1.1
>



-- 
Paulo Zanoni