From mboxrd@z Thu Jan 1 00:00:00 1970 From: Daniel Vetter Subject: Re: [PATCH v2] drm: Improve manual IRQ installation documentation Date: Mon, 24 Jun 2013 09:38:16 +0200 Message-ID: <20130624073816.GD5823@phenom.ffwll.local> References: <1371903059-12094-1-git-send-email-laurent.pinchart+renesas@ideasonboard.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: Received: from mail-ea0-f170.google.com (mail-ea0-f170.google.com [209.85.215.170]) by gabe.freedesktop.org (Postfix) with ESMTP id 2A2C7E5DD4 for ; Mon, 24 Jun 2013 00:38:19 -0700 (PDT) Received: by mail-ea0-f170.google.com with SMTP id h10so5823699eaj.15 for ; Mon, 24 Jun 2013 00:38:18 -0700 (PDT) Content-Disposition: inline In-Reply-To: <1371903059-12094-1-git-send-email-laurent.pinchart+renesas@ideasonboard.com> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: dri-devel-bounces+sf-dri-devel=m.gmane.org@lists.freedesktop.org Errors-To: dri-devel-bounces+sf-dri-devel=m.gmane.org@lists.freedesktop.org To: Laurent Pinchart Cc: dri-devel@lists.freedesktop.org List-Id: dri-devel@lists.freedesktop.org On Sat, Jun 22, 2013 at 02:10:59PM +0200, Laurent Pinchart wrote: > Signed-off-by: Laurent Pinchart Hm, a bit a thin commit message, but changes look good. So with the commit message patched up this is Reviewed-by: Daniel Vetter > --- > Documentation/DocBook/drm.tmpl | 118 ++++++++++++++++++++++++----------------- > 1 file changed, 70 insertions(+), 48 deletions(-) > > Changes since v1: > > - Document manual IRQ registration > > diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl > index 91ee107..a608094 100644 > --- a/Documentation/DocBook/drm.tmpl > +++ b/Documentation/DocBook/drm.tmpl > @@ -186,11 +186,12 @@ > > DRIVER_HAVE_IRQDRIVER_IRQ_SHARED > > - DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler. The > - DRM core will automatically register an interrupt handler when the > - flag is set. DRIVER_IRQ_SHARED indicates whether the device & > - handler support shared IRQs (note that this is required of PCI > - drivers). > + DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler > + managed by the DRM Core. The core will support simple IRQ handler > + installation when the flag is set. The installation process is > + described in . > + DRIVER_IRQ_SHARED indicates whether the device & handler > + support shared IRQs (note that this is required of PCI drivers). > > > > @@ -344,50 +345,71 @@ char *date; > The DRM core tries to facilitate IRQ handler registration and > unregistration by providing drm_irq_install and > drm_irq_uninstall functions. Those functions only > - support a single interrupt per device. > - > - > - > - Both functions get the device IRQ by calling > - drm_dev_to_irq. This inline function will call a > - bus-specific operation to retrieve the IRQ number. For platform devices, > - platform_get_irq(..., 0) is used to retrieve the > - IRQ number. > - > - > - 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 IRQ will then be requested by a call to > - 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 > - 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. > - > - > - 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 free_irq. > + support a single interrupt per device, devices that use more than one > + IRQs need to be handled manually. > > + > + Managed IRQ Registration > + > + Both the drm_irq_install and > + drm_irq_uninstall functions get the device IRQ by > + calling drm_dev_to_irq. This inline function will > + call a bus-specific operation to retrieve the IRQ number. For platform > + devices, platform_get_irq(..., 0) is used to > + retrieve the IRQ number. > + > + > + 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 IRQ will then be requested by a call to > + 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 > + 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. > + > + > + 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 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 request_irq > + and free_irq functions, or their devm_* equivalent). > + > + > + 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 > + drm_device irq_enabled > + field to 1 upon registration of the IRQs, and clear it to 0 after > + unregistering the IRQs. > + > + > > > Memory Manager Initialization > -- > Regards, > > Laurent Pinchart > -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch