[PATCH v2] drm: Improve manual IRQ installation documentation

[Daniel Vetter]

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
> +

Re: [PATCH v2] drm: Improve manual IRQ installation documentation

[Daniel Vetter]

On Sat, Jun 22, 2013 at 02:10:59PM +0200, Laurent Pinchart wrote:
 Signed-off-by: Laurent Pinchart laurent.pinchart+rene...@ideasonboard.com

Hm, a bit a thin commit message, but changes look good. So with the commit
message patched up this is

Reviewed-by: Daniel Vetter daniel.vet...@ffwll.ch

 ---
  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 @@
varlistentry
  termDRIVER_HAVE_IRQ/termtermDRIVER_IRQ_SHARED/term
  listitempara
 -  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 
 amp;
 -  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 xref linkend=drm-irq-registration/./para
 +  paraDRIVER_IRQ_SHARED indicates whether the device amp; 
 handler
 +  support shared IRQs (note that this is required of PCI  
 drivers).
  /para/listitem
/varlistentry
varlistentry
 @@ -344,50 +345,71 @@ char *date;/synopsis
The DRM core tries to facilitate IRQ handler registration and
unregistration by providing functiondrm_irq_install/function 
 and
functiondrm_irq_uninstall/function functions. Those functions 
 only
 -  support a single interrupt per device.
 -/para
 -  !--!Fdrivers/char/drm/drm_irq.c drm_irq_install--
 -para
 -  Both functions get the device IRQ by calling
 -  functiondrm_dev_to_irq/function. This inline function will 
 call a
 -  bus-specific operation to retrieve the IRQ number. For platform 
 devices,
 -  functionplatform_get_irq/function(..., 0) is used to retrieve 
 the
 -  IRQ number.
 -/para
 -para
 -  functiondrm_irq_install/function starts by calling the
 -  methodnameirq_preinstall/methodname 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.
 -/para
 -para
 -  The IRQ will then be requested by a call to
 -  functionrequest_irq/function. If the DRIVER_IRQ_SHARED driver
 -  feature flag is set, a shared (IRQF_SHARED) IRQ handler will be
 -  requested.
 -/para
 -para
 -  The IRQ handler function must be provided as the mandatory 
 irq_handler
 -  driver operation. It will get passed directly to
 -  functionrequest_irq/function 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.
 -/para
 -para
 -  Finally the function calls the optional
 -  methodnameirq_postinstall/methodname 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.
 -/para
 -para
 -  functiondrm_irq_uninstall/function 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
 -  methodnameirq_uninstall/methodname driver operation. The 
 operation
 -  must disable all hardware interrupts. Finally the function frees 
 the IRQ
 -  by calling functionfree_irq/function.
 +  support a single interrupt per device, devices that use more than 
 one
 +  IRQs need to be handled manually.
  /para
 +sect4
 +  titleManaged IRQ Registration/title
 +  para
 +Both the functiondrm_irq_install/function and
 + functiondrm_irq_uninstall/function functions get the device IRQ 
 by
 + calling functiondrm_dev_to_irq/function. This inline function 
 will
 + call a bus-specific operation to retrieve the IRQ number. For 
 platform
 + devices, functionplatform_get_irq/function(..., 0) is used to
 + retrieve the IRQ number.
 +  /para
 +  

[PATCH v2] drm: Improve manual IRQ installation documentation

[Laurent Pinchart]

Signed-off-by: Laurent Pinchart 
---
 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.
+  
+  
+  

[PATCH v2] drm: Improve manual IRQ installation documentation

[Laurent Pinchart]

Signed-off-by: Laurent Pinchart laurent.pinchart+rene...@ideasonboard.com
---
 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 @@
   varlistentry
 termDRIVER_HAVE_IRQ/termtermDRIVER_IRQ_SHARED/term
 listitempara
-  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 amp;
-  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 xref linkend=drm-irq-registration/./para
+  paraDRIVER_IRQ_SHARED indicates whether the device amp; 
handler
+  support shared IRQs (note that this is required of PCI  drivers).
 /para/listitem
   /varlistentry
   varlistentry
@@ -344,50 +345,71 @@ char *date;/synopsis
   The DRM core tries to facilitate IRQ handler registration and
   unregistration by providing functiondrm_irq_install/function and
   functiondrm_irq_uninstall/function functions. Those functions 
only
-  support a single interrupt per device.
-/para
-  !--!Fdrivers/char/drm/drm_irq.c drm_irq_install--
-para
-  Both functions get the device IRQ by calling
-  functiondrm_dev_to_irq/function. This inline function will call a
-  bus-specific operation to retrieve the IRQ number. For platform 
devices,
-  functionplatform_get_irq/function(..., 0) is used to retrieve the
-  IRQ number.
-/para
-para
-  functiondrm_irq_install/function starts by calling the
-  methodnameirq_preinstall/methodname 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.
-/para
-para
-  The IRQ will then be requested by a call to
-  functionrequest_irq/function. If the DRIVER_IRQ_SHARED driver
-  feature flag is set, a shared (IRQF_SHARED) IRQ handler will be
-  requested.
-/para
-para
-  The IRQ handler function must be provided as the mandatory 
irq_handler
-  driver operation. It will get passed directly to
-  functionrequest_irq/function 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.
-/para
-para
-  Finally the function calls the optional
-  methodnameirq_postinstall/methodname 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.
-/para
-para
-  functiondrm_irq_uninstall/function 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
-  methodnameirq_uninstall/methodname driver operation. The 
operation
-  must disable all hardware interrupts. Finally the function frees the 
IRQ
-  by calling functionfree_irq/function.
+  support a single interrupt per device, devices that use more than one
+  IRQs need to be handled manually.
 /para
+sect4
+  titleManaged IRQ Registration/title
+  para
+Both the functiondrm_irq_install/function and
+   functiondrm_irq_uninstall/function functions get the device IRQ 
by
+   calling functiondrm_dev_to_irq/function. This inline function 
will
+   call a bus-specific operation to retrieve the IRQ number. For 
platform
+   devices, functionplatform_get_irq/function(..., 0) is used to
+   retrieve the IRQ number.
+  /para
+  para
+functiondrm_irq_install/function starts by calling the
+methodnameirq_preinstall/methodname 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.
+  /para
+