Merge tag 'drm-misc-next-2017-06-02' of git://anongit.freedesktop.org/git/drm-misc into drm-next

Core Changes:
- Stop proliferation of drm_vblank_cleanup by adding to the docs and deleting
  boilerplate (Daniel)
- Roll out and use mode_valid hooks across crtc/encoder/bridge (Jose)
- Add drm_vblank.[hc] to isolate vblank code from optional irq helpers (Daniel)

Driver Changes:
- Replace drm_for_each_connector with drm_for_each_connector_iter (Gustavo)
- A couple misc driver fixes

Cc: Gustavo Padovan <gustavo.padovan@collabora.com>
Cc: Jose Abreu <Jose.Abreu@synopsys.com>
Cc: Daniel Vetter <daniel.vetter@intel.com>

* tag 'drm-misc-next-2017-06-02' of git://anongit.freedesktop.org/git/drm-misc: (34 commits)
  drm/vc4: Mark the device as active when enabling runtime PM.
  drm: remove writeq/readq function definitions
  drm/atmel-hlcdc: Use crtc->mode_valid() callback
  drm/exynos: Drop drm_vblank_cleanup
  drm/hdlcd|mali: Drop drm_vblank_cleanup
  drm/doc: Polish irq helper documentation
  drm: Extract drm_vblank.[hc]
  drm/vc4: Fix comment in vc4_drv.h
  drm/pl111: fix warnings without CONFIG_ARM_AMBA
  drm/atomic: Consitfy mode parameter to drm_atomic_set_mode_for_crtc()
  drm/arcgpu: Drop drm_vblank_cleanup
  drm/atmel: Drop drm_vblank_cleanup
  drm/imx: Drop drm_vblank_cleanup
  drm/meson: Drop drm_vblank_cleanup
  drm/stm: Drop drm_vblank_cleanup
  drm/sun4i: Drop drm_vblank_cleanup
  drm: better document how to send out the crtc disable event
  drm: Use vsnprintf extension %ph
  drm/doc: move printf helpers out of drmP.h
  drm/pl111: select DRM_PANEL
  ...

1 files changed, 31 insertions, 2 deletions

diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
index e64e33b9dd26..18f3181674e8 100644
--- a/include/drm/drm_drv.h
+++ b/include/drm/drm_drv.h
@@ -327,11 +327,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);
 
 	/**