All of lore.kernel.org
 help / color / mirror / Atom feed
From: Stefan Agner <stefan@agner.ch>
To: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Daniel Vetter <daniel.vetter@intel.com>,
	Intel Graphics Development <intel-gfx@lists.freedesktop.org>,
	DRI Development <dri-devel@lists.freedesktop.org>
Subject: Re: [PATCH 08/37] drm/doc: Polish irq helper documentation
Date: Thu, 25 May 2017 00:46:29 -0700	[thread overview]
Message-ID: <8e0066435062cc6b61eb8b5948df1519@agner.ch> (raw)
In-Reply-To: <20170524145212.27837-9-daniel.vetter@ffwll.ch>

On 2017-05-24 07:51, Daniel Vetter wrote:
> Pull a (much shorter) overview into drm_irq.c, and instead put the
> callback documentation into in-line comments in drm_drv.h.

Looks good and just found all I needed to know to fix IRQ registration
in fsl dcu.

Reviewed-by: Stefan Agner <stefan@agner.ch>

> 
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
>  Documentation/gpu/drm-internals.rst | 62 +++++--------------------------------
>  drivers/gpu/drm/drm_irq.c           | 30 +++++++++++++++---
>  drivers/gpu/drm/drm_vblank.c        |  3 ++
>  include/drm/drmP.h                  |  9 ++++--
>  include/drm/drm_drv.h               | 33 ++++++++++++++++++--
>  5 files changed, 74 insertions(+), 63 deletions(-)
> 
> diff --git a/Documentation/gpu/drm-internals.rst
> b/Documentation/gpu/drm-internals.rst
> index d218dd29221a..82b406d3d377 100644
> --- a/Documentation/gpu/drm-internals.rst
> +++ b/Documentation/gpu/drm-internals.rst
> @@ -149,60 +149,14 @@ Device Instance and Driver Handling
>  Driver Load
>  -----------
>  
> -IRQ Registration
> -~~~~~~~~~~~~~~~~
> -
> -The DRM core tries to facilitate IRQ handler registration and
> -unregistration by providing :c:func:`drm_irq_install()` and
> -:c:func:`drm_irq_uninstall()` functions. Those functions only
> -support a single interrupt per device, devices that use more than one
> -IRQs need to be handled manually.
> -
> -Managed IRQ Registration
> -''''''''''''''''''''''''
> -
> -:c:func:`drm_irq_install()` starts by calling the irq_preinstall
> -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.
> -
> -The passed-in IRQ will then be requested by a call to
> -:c:func:`request_irq()`. If the DRIVER_IRQ_SHARED driver feature
> -flag is set, a shared (IRQF_SHARED) IRQ handler will be requested.
> -
> -The IRQ handler function must be provided as the mandatory irq_handler
> -driver operation. It will get passed directly to
> -:c:func:`request_irq()` 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.
> -
> -Finally the function calls the optional irq_postinstall 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.
> -
> -:c:func:`drm_irq_uninstall()` 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
> -irq_uninstall driver operation. The operation must disable all hardware
> -interrupts. Finally the function frees the IRQ by calling
> -:c:func:`free_irq()`.
> -
> -Manual IRQ Registration
> -'''''''''''''''''''''''
> -
> -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 :c:func:`request_irq()` and
> -:c:func:`free_irq()` functions, or their :c:func:`devm_request_irq()` and
> -:c:func:`devm_free_irq()` equivalents).
> -
> -When manually registering IRQs, drivers must not set the
> -DRIVER_HAVE_IRQ driver feature flag, and must not provide the
> -irq_handler driver operation. They must set the :c:type:`struct
> -drm_device <drm_device>` irq_enabled field to 1 upon
> -registration of the IRQs, and clear it to 0 after unregistering the
> -IRQs.
> +IRQ Helper Library
> +~~~~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_irq.c
> +   :doc: irq helpers
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_irq.c
> +   :export:
>  
>  Memory Manager Initialization
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c
> index 28d736c3fcb4..3b04c25100ae 100644
> --- a/drivers/gpu/drm/drm_irq.c
> +++ b/drivers/gpu/drm/drm_irq.c
> @@ -62,19 +62,39 @@
>  #include "drm_internal.h"
>  
>  /**
> + * DOC: irq helpers
> + *
> + * The DRM core provides very simple support helpers to enable IRQ
> handling on a
> + * device through the drm_irq_install() and drm_irq_uninstall() functions. This
> + * only supports devices with a single interrupt on the main device stored in
> + * &drm_device.dev and set as the device paramter in drm_dev_alloc().
> + *
> + * These IRQ helpers are strictly optional. Drivers which roll their own only
> + * need to set &drm_device.irq_enabled to signal the DRM core that vblank
> + * interrupts are working. Since these helpers don't automatically clean up the
> + * requested interrupt like e.g. devm_request_irq() they're not really
> + * recommended.
> + */
> +
> +/**
>   * drm_irq_install - install IRQ handler
>   * @dev: DRM device
>   * @irq: IRQ number to install the handler for
>   *
>   * Initializes the IRQ related data. Installs the handler, calling the driver
> - * irq_preinstall() and irq_postinstall() functions before and after the
> - * installation.
> + * &drm_driver.irq_preinstall and &drm_driver.irq_postinstall functions before
> + * and after the installation.
>   *
>   * This is the simplified helper interface provided for drivers with no special
>   * needs. Drivers which need to install interrupt handlers for multiple
>   * interrupts must instead set &drm_device.irq_enabled to signal the DRM core
>   * that vblank interrupts are available.
>   *
> + * @irq must match the interrupt number that would be passed to request_irq(),
> + * if called directly instead of using this helper function.
> + *
> + * &drm_driver.irq_handler is called to handle the registered interrupt.
> + *
>   * Returns:
>   * Zero on success or a negative error code on failure.
>   */
> @@ -136,9 +156,9 @@ EXPORT_SYMBOL(drm_irq_install);
>   * drm_irq_uninstall - uninstall the IRQ handler
>   * @dev: DRM device
>   *
> - * Calls the driver's irq_uninstall() function and unregisters the IRQ handler.
> - * This should only be called by drivers which used drm_irq_install() to set up
> - * their interrupt handler. Other drivers must only reset
> + * Calls the driver's &drm_driver.irq_uninstall function and
> unregisters the IRQ
> + * handler.  This should only be called by drivers which used drm_irq_install()
> + * to set up their interrupt handler. Other drivers must only reset
>   * &drm_device.irq_enabled to false.
>   *
>   * Note that for kernel modesetting drivers it is a bug if this function fails.
> diff --git a/drivers/gpu/drm/drm_vblank.c b/drivers/gpu/drm/drm_vblank.c
> index 630dc26379b7..463e4d81fb0d 100644
> --- a/drivers/gpu/drm/drm_vblank.c
> +++ b/drivers/gpu/drm/drm_vblank.c
> @@ -363,6 +363,9 @@ static void vblank_disable_fn(unsigned long arg)
>   * @dev: DRM device
>   *
>   * This function cleans up any resources allocated in drm_vblank_init.
> + *
> + * Drivers which don't use drm_irq_install() need to set
> &drm_device.irq_enabled
> + * themselves, to signal to the DRM core that vblank interrupts are enabled.
>   */
>  void drm_vblank_cleanup(struct drm_device *dev)
>  {
> diff --git a/include/drm/drmP.h b/include/drm/drmP.h
> index 2e0b76cceb97..39df16af7a4a 100644
> --- a/include/drm/drmP.h
> +++ b/include/drm/drmP.h
> @@ -377,8 +377,13 @@ struct drm_device {
>  	int last_context;		/**< Last current context */
>  	/*@} */
>  
> -	/** \name VBLANK IRQ support */
> -	/*@{ */
> +	/**
> +	 * @irq_enabled:
> +	 *
> +	 * Indicates that interrupt handling is enabled, specifically vblank
> +	 * handling. Drivers which don't use drm_irq_install() need to set this
> +	 * to true manually.
> +	 */
>  	bool irq_enabled;
>  	int irq;
>  
> diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
> index ebb41688581b..f495eee01302 100644
> --- a/include/drm/drm_drv.h
> +++ b/include/drm/drm_drv.h
> @@ -325,11 +325,40 @@ struct drm_driver {
>  				     struct timeval *vblank_time,
>  				     bool in_vblank_irq);
>  
> -	/* these have to be filled in */
> -
> +	/**
> +	 * @irq_handler:
> +	 *
> +	 * Interrupt handler called when using drm_irq_install(). Not used by
> +	 * drivers which implement their own interrupt handling.
> +	 */
>  	irqreturn_t(*irq_handler) (int irq, void *arg);
> +
> +	/**
> +	 * @irq_preinstall:
> +	 *
> +	 * Optional callback used by drm_irq_install() which is called before
> +	 * the interrupt handler is registered. This should be used to clear out
> +	 * any pending interrupts (from e.g. firmware based drives) and reset
> +	 * the interrupt handling registers.
> +	 */
>  	void (*irq_preinstall) (struct drm_device *dev);
> +
> +	/**
> +	 * @irq_postinstall:
> +	 *
> +	 * Optional callback used by drm_irq_install() which is called after
> +	 * the interrupt handler is registered. This should be used to enable
> +	 * interrupt generation in the hardware.
> +	 */
>  	int (*irq_postinstall) (struct drm_device *dev);
> +
> +	/**
> +	 * @irq_uninstall:
> +	 *
> +	 * Optional callback used by drm_irq_uninstall() which is called before
> +	 * the interrupt handler is unregistered. This should be used to disable
> +	 * interrupt generation in the hardware.
> +	 */
>  	void (*irq_uninstall) (struct drm_device *dev);
>  
>  	/**
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

  reply	other threads:[~2017-05-25  7:46 UTC|newest]

Thread overview: 94+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-05-24 14:51 [PATCH 00/37] drm: more doc work&cleanup, mostly vblank related Daniel Vetter
2017-05-24 14:51 ` [PATCH 01/37] drm/doc: move printf helpers out of drmP.h Daniel Vetter
2017-05-30  7:33   ` Neil Armstrong
2017-05-24 14:51 ` [PATCH 02/37] drm: Remove drm_device->virtdev Daniel Vetter
2017-05-24 14:51 ` Daniel Vetter
2017-05-29  6:52   ` Gerd Hoffmann
2017-05-29  6:52   ` Gerd Hoffmann
2017-05-30  7:33   ` Neil Armstrong
2017-05-30  7:33   ` Neil Armstrong
2017-05-24 14:51 ` [PATCH 03/37] drm/udl: Remove dummy busid callback Daniel Vetter
2017-05-24 14:51 ` [PATCH 04/37] drm: Remove drm_driver->set_busid hook Daniel Vetter
2017-05-24 14:51 ` [PATCH 05/37] drm/pci: Deprecate drm_pci_init/exit completely Daniel Vetter
2017-05-24 14:51 ` [PATCH 06/37] drm/doc: Improve ioctl/fops docs a bit more Daniel Vetter
2017-05-31  9:20   ` [PATCH] " Daniel Vetter
2017-05-24 14:51 ` [PATCH 07/37] drm: Extract drm_vblank.[hc] Daniel Vetter
2017-05-29 19:36   ` Stefan Agner
2017-05-31  8:04     ` Daniel Vetter
2017-05-31  9:21   ` [PATCH] " Daniel Vetter
2017-05-31 17:51     ` Stefan Agner
2017-06-01  5:55       ` Daniel Vetter
2017-05-31 18:22     ` kbuild test robot
2017-05-24 14:51 ` [PATCH 08/37] drm/doc: Polish irq helper documentation Daniel Vetter
2017-05-25  7:46   ` Stefan Agner [this message]
2017-05-29 18:58     ` Daniel Vetter
2017-05-31  9:22   ` [PATCH] " Daniel Vetter
2017-05-24 14:51 ` [PATCH 09/37] drm/doc: Drop empty include for drm_color_mgmt.h Daniel Vetter
2017-05-24 14:51 ` [PATCH 10/37] drm/doc: vblank cleanup Daniel Vetter
2017-06-15 12:58   ` Thierry Reding
2017-06-20  8:18     ` Daniel Vetter
2017-05-24 14:51 ` [PATCH 11/37] drm/vblank: _ioctl posfix for ioctl handler Daniel Vetter
2017-05-24 14:51 ` [PATCH 12/37] drm/vblank: Consistent drm_crtc_ prefix Daniel Vetter
2017-05-24 14:51 ` [PATCH 13/37] drm: better document how to send out the crtc disable event Daniel Vetter
2017-05-24 14:54   ` Boris Brezillon
2017-05-30  7:35   ` Neil Armstrong
2017-05-24 14:51 ` [PATCH 14/37] drm/amd|radeon: Drop drm_vblank_cleanup Daniel Vetter
2017-05-24 14:51 ` [PATCH 15/37] drm/arcgpu: " Daniel Vetter
2017-05-24 14:57   ` Alexey Brodkin
2017-05-24 14:51 ` [PATCH 16/37] drm/hdlcd|mali: " Daniel Vetter
2017-05-31 10:57   ` Liviu Dudau
2017-05-31 11:03     ` Daniel Vetter
2017-05-31 11:22       ` Liviu Dudau
2017-05-31 16:41         ` Daniel Vetter
2017-05-31 16:57           ` Liviu Dudau
2017-06-01  5:55             ` Daniel Vetter
2017-05-31 16:37   ` Liviu Dudau
2017-06-01  6:01     ` [Intel-gfx] " Daniel Vetter
2017-05-24 14:51 ` [PATCH 17/37] drm/atmel: " Daniel Vetter
2017-05-24 15:19   ` Boris Brezillon
2017-05-24 14:51 ` [PATCH 18/37] drm/exynos: " Daniel Vetter
2017-05-30  0:03   ` Inki Dae
2017-05-31  8:45     ` Daniel Vetter
2017-06-01  6:15       ` Inki Dae
2017-06-01  9:44         ` Daniel Vetter
2017-05-24 14:51 ` [PATCH 19/37] drm/fsl: " Daniel Vetter
2017-05-25  8:18   ` Stefan Agner
2017-05-26  7:00     ` Daniel Vetter
2017-05-30 21:17       ` Stefan Agner
2017-05-31  8:52         ` Daniel Vetter
2017-06-08 21:42           ` Stefan Agner
2017-05-24 14:51 ` [PATCH 20/37] drm/hibmc: " Daniel Vetter
2017-05-24 14:51 ` [PATCH 21/37] drm/kirin: " Daniel Vetter
2017-05-24 14:51 ` [PATCH 22/37] drm/i915: " Daniel Vetter
2017-05-24 14:51 ` [PATCH 23/37] drm/imx: " Daniel Vetter
2017-05-29 11:07   ` Philipp Zabel
2017-05-31  8:51     ` Daniel Vetter
2017-05-24 14:51 ` [PATCH 24/37] drm/mtk: " Daniel Vetter
2017-05-24 14:52 ` [PATCH 25/37] drm/meson: " Daniel Vetter
2017-05-24 15:46   ` Neil Armstrong
2017-05-24 14:52 ` [PATCH 26/37] drm/mxsfb: " Daniel Vetter
     [not found] ` <20170524145212.27837-1-daniel.vetter-/w4YWyX8dFk@public.gmane.org>
2017-05-24 14:52   ` [PATCH 27/37] drm/nouveau: " Daniel Vetter
2017-05-24 14:52 ` [PATCH 28/37] drm/rockchip: " Daniel Vetter
2017-05-24 14:52 ` [PATCH 29/37] drm/shmob: " Daniel Vetter
2017-05-24 14:52 ` [PATCH 30/37] drm/sti: " Daniel Vetter
2017-06-01 15:37   ` Vincent ABRIOU
2017-06-20  8:20     ` Daniel Vetter
2017-05-24 14:52 ` [PATCH 31/37] drm/stm: " Daniel Vetter
2017-05-29  8:09   ` Philippe CORNU
2017-05-24 14:52 ` [PATCH 32/37] drm/sun4i: " Daniel Vetter
2017-05-29  7:43   ` Maxime Ripard
2017-05-24 14:52 ` [PATCH 33/37] drm/tegra: " Daniel Vetter
2017-06-15 13:00   ` Thierry Reding
2017-06-20  8:21     ` Daniel Vetter
2017-05-24 14:52 ` [PATCH 34/37] drm/udl: " Daniel Vetter
2017-05-24 14:52 ` [PATCH 35/37] drm/vmwgfx: " Daniel Vetter
2017-06-03  5:10   ` Sinclair Yeh
2017-05-24 14:52 ` [PATCH 36/37] drm/zte: " Daniel Vetter
2017-05-25  3:01   ` Shawn Guo
2017-05-26  6:57     ` Daniel Vetter
2017-05-26 11:04       ` Shawn Guo
2017-05-24 14:52 ` [PATCH 37/37] drm/vblank: Unexport drm_vblank_cleanup Daniel Vetter
2017-05-24 15:12 ` ✓ Fi.CI.BAT: success for drm: more doc work&cleanup, mostly vblank related Patchwork
2017-05-24 15:19 ` [PATCH 00/37] " Chris Wilson
2017-05-24 15:54   ` [Intel-gfx] " Daniel Vetter
2017-05-31 10:05 ` ✓ Fi.CI.BAT: success for drm: more doc work&cleanup, mostly vblank related (rev4) Patchwork

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=8e0066435062cc6b61eb8b5948df1519@agner.ch \
    --to=stefan@agner.ch \
    --cc=daniel.vetter@ffwll.ch \
    --cc=daniel.vetter@intel.com \
    --cc=dri-devel@lists.freedesktop.org \
    --cc=intel-gfx@lists.freedesktop.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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.