[Intel-gfx] [PATCH 2/2] drm/i915/hotplug: document the hotplug handling in the driver

[Daniel Vetter]

On Mon, Jul 06, 2015 at 12:26:15PM +0530, Sivakumar Thulasimani wrote:
> 
> 
> On 7/2/2015 6:35 PM, Jani Nikula wrote:
> >Add an overview of the drm/i915 hotplug handling.
> >
> >Signed-off-by: Jani Nikula <jani.nikula at intel.com>
> >---
> >  Documentation/DocBook/drm.tmpl       |  5 +++++
> >  drivers/gpu/drm/i915/intel_hotplug.c | 39 ++++++++++++++++++++++++++++++++++++
> >  2 files changed, 44 insertions(+)
> >
> >diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> >index c0312cbd023d..e82205ee3d5f 100644
> >--- a/Documentation/DocBook/drm.tmpl
> >+++ b/Documentation/DocBook/drm.tmpl
> >@@ -4045,6 +4045,11 @@ int num_ioctls;</synopsis>
> >          </para>
> >        </sect2>
> >        <sect2>
> >+        <title>Hotplug</title>
> >+!Pdrivers/gpu/drm/i915/intel_hotplug.c Hotplug
> >+!Idrivers/gpu/drm/i915/intel_hotplug.c
> >+      </sect2>
> >+      <sect2>
> >  	<title>High Definition Audio</title>
> >  !Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port
> >  !Idrivers/gpu/drm/i915/intel_audio.c
> >diff --git a/drivers/gpu/drm/i915/intel_hotplug.c b/drivers/gpu/drm/i915/intel_hotplug.c
> >index 3c53aac71d98..bac91a158ca2 100644
> >--- a/drivers/gpu/drm/i915/intel_hotplug.c
> >+++ b/drivers/gpu/drm/i915/intel_hotplug.c
> >@@ -29,6 +29,45 @@
> >  #include "i915_drv.h"
> >  #include "intel_drv.h"
> >+/**
> >+ * DOC: Hotplug
> >+ *
> >+ * Simply put, hotplug occurs when a display is connected to or disconnected
> >+ * from the system. However, there may be adapters and docking stations and
> >+ * Display Port short pulses and MST devices involved, complicating matters.
> >+ *
> >+ * Hotplug in i915 is handled in many different levels of abstraction.
> >+ *
> >+ * The platform dependent interrupt handling code in i915_irq.c enables,
> >+ * disables, and does preliminary handling of the interrupts. The interrupt
> >+ * handlers gather the hotplug detect (HPD) information from relevant registers
> >+ * into a platform independent mask of hotplug pins that have fired.
> >+ *
> >+ * The platform independent interrupt handler intel_hpd_irq_handler() in
> >+ * intel_hotplug.c does hotplug irq storm detection and mitigation, and passes
> >+ * further processing to appropriate bottom halves (Display Port specific and
> >+ * regular hotplug).
> >+ *
> >+ * The Display Port work function i915_digport_work_func() calls into
> >+ * intel_dp_hpd_pulse() via hooks, which handles DP short pulses and DP MST long
> >+ * pulses, with failures and non-MST long pulses triggering regular hotplug
> >+ * processing on the connector.
> >+ *
> >+ * The regular hotplug work function i915_hotplug_work_func() calls connector
> >+ * detect hooks, and, if connector status changes, triggers sending of hotplug
> >+ * uevent to userspace via drm_kms_helper_hotplug_event().
> >+ *
> >+ * Finally, the userspace is responsible for triggering a modeset upon receiving
> >+ * the hotplug uevent, disabling or enabling the crtc as needed.
> >+ *
> >+ * The hotplug interrupt storm detection and mitigation code keeps track of the
> >+ * number of interrupts per hotplug pin per a period of time, and if the number
> >+ * of interrupts exceeds a certain threshold, the interrupt is disabled for a
> >+ * while before being re-enabled. The intention is to mitigate issues raising
> >+ * from broken hardware triggering massive amounts of interrupts and grinding
> >+ * the system to a halt.
> >+ */
> >+
> >  enum port intel_hpd_pin_to_port(enum hpd_pin pin)
> >  {
> >  	switch (pin) {
> can we add that HPD storm is not expected in case of Displayport as
> discussed in other thread and
> so is not handled in i915_digport_work_func ?

Good suggestion, but Jani's on vacation now for a few weeks. Can you pls
submit a follow-up patch to add that? I've merged these two meanwhile.

Thanks, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch