[Intel-gfx] [PATCH 08/37] drm/doc: Polish irq helper documentation

Stefan Agner stefan at agner.ch
Thu May 25 07:46:29 UTC 2017


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 at agner.ch>

> 
> Signed-off-by: Daniel Vetter <daniel.vetter at 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);
>  
>  	/**


More information about the Intel-gfx mailing list