[FE training-materials-updates] Kernel course: now recommend managed routines for IRQ request / free

[Michael Opdenacker]

Repository : git://git.free-electrons.com/training-materials.git

On branch  : master
Link       : http://git.free-electrons.com/training-materials/commit/?id=717fad24efcd5de538221100800cb02a6dd200e5

>---------------------------------------------------------------

commit 717fad24efcd5de538221100800cb02a6dd200e5
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Wed Feb 5 05:54:45 2014 +0100

    Kernel course: now recommend managed routines for IRQ request / free
    
    Signed-off-by: Michael Opdenacker <michael.opdenacker at free-electrons.com>


>---------------------------------------------------------------

717fad24efcd5de538221100800cb02a6dd200e5
 .../kernel-serial-interrupt.tex                    |    8 +-
 .../kernel-driver-development-interrupts.tex       |   96 +++++++++++---------
 2 files changed, 55 insertions(+), 49 deletions(-)

diff --git a/labs/kernel-serial-interrupt/kernel-serial-interrupt.tex b/labs/kernel-serial-interrupt/kernel-serial-interrupt.tex
index 33ed64d..97ef2a8 100644
--- a/labs/kernel-serial-interrupt/kernel-serial-interrupt.tex
+++ b/labs/kernel-serial-interrupt/kernel-serial-interrupt.tex
@@ -48,7 +48,7 @@ hardware IRQ number from the device tree and get a virtual IRQ number.
 dev->irq = irq_of_parse_and_map(pdev->dev.of_node, 0);
 \end{verbatim}
 
-Then, pass the newly created virtual interrupt to \code{request_irq()}
+Then, pass the newly created virtual interrupt to \code{devm_request_irq()}
 along with the interrupt handler to register your interrupt in the
 kernel.
 
@@ -88,12 +88,6 @@ check your code once again and ask your instructor for clarification!
 Load and unload your driver multiple times, to make sure that 
 there are no registration / deregistration issues.
 
-Note: pay attention to where you place the call to \code{free_irq()}.
-Think about possible race conditions (typically because of resources
-not unregistered or freed in the right order, and the interference of
-user-space requests or hardware events happening at the same time). 
-Don't hesitate to discuss the question with your instructor.
-
 \section{Sleeping, waking up and communication}
 
 Now, we would like to implement the \code{read()} operation of our
diff --git a/slides/kernel-driver-development-interrupts/kernel-driver-development-interrupts.tex b/slides/kernel-driver-development-interrupts/kernel-driver-development-interrupts.tex
index 61b50f6..e3321f6 100644
--- a/slides/kernel-driver-development-interrupts/kernel-driver-development-interrupts.tex
+++ b/slides/kernel-driver-development-interrupts/kernel-driver-development-interrupts.tex
@@ -2,32 +2,42 @@
 
 \begin{frame}[fragile]
   \frametitle{Registering an interrupt handler 1/2}
+  The "managed" API is recommended:
+  \begin{minted}{c}
+int devm_request_irq(struct device *dev,
+                     unsigned int irq,
+                     irq_handler_t handler,
+                     unsigned long irq_flags,
+                     const char *devname,
+                     void *dev_id);
+  \end{minted}
   \begin{itemize}
-  \item \begin{minted}{c}
-int request_irq(unsigned int irq,
-     irq_handler_t handler, unsigned long irq_flags,
-     const char *devname, void *dev_id);
-   \end{minted}
-   \begin{itemize}
-   \item Register an interrupt handler.
-   \item \code{irq} is the requested IRQ channel. For platform
-     devices, use \kfunc{platform_get_irq} to retrieve the
-     interrupt number.
-   \item \code{handler} is a pointer to the IRQ handler
-   \item \code{irq_flags} are option masks (see next slide)
-   \item \code{devname} is the registered name
-   \item \code{dev_id} is a pointer to some data. It cannot be NULL
-     as it is used as an identifier for \kfunc{free_irq} when using
-     shared IRQs.
-   \end{itemize}
- \item \begin{minted}{c}
-void free_irq(unsigned int irq, void *dev_id);
-\end{minted}
-\begin{itemize}
-\item Release an interrupt handler.
-\end{itemize}
- \item Defined in \kpath{include/linux/interrupt.h}
- \end{itemize}
+  \item Register an interrupt handler.
+  \item \code{device} for automatic freeing at device or module
+        release time.
+  \item \code{irq} is the requested IRQ channel. For platform
+        devices, use \kfunc{platform_get_irq} to retrieve the
+        interrupt number.
+  \item \code{handler} is a pointer to the IRQ handler
+  \item \code{irq_flags} are option masks (see next slide)
+  \item \code{devname} is the registered name
+  \item \code{dev_id} is a pointer to some data. It cannot be NULL
+        as it is used as an identifier for \kfunc{free_irq} when using
+        shared IRQs.
+  \end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+  \frametitle{Releasing an interrupt handler}
+  \begin{minted}{c}
+void free_irq(struct device *dev,
+              unsigned int irq, void *dev_id);
+  \end{minted}
+  \begin{itemize}
+  \item Explicitely release an interrupt handler. Done automatically
+        in normal situations.
+  \end{itemize}
+  Defined in \kpath{include/linux/interrupt.h}
 \end{frame}
 
 \begin{frame}
@@ -129,24 +139,26 @@ Err:    0
 
 \begin{frame}[fragile]
   \frametitle{Threaded interrupts}
+  In 2.6.30, support for threaded interrupts has been added to
+  the Linux kernel
   \begin{itemize}
-  \item In 2.6.30, support for threaded interrupts has been added to
-    the Linux kernel
-    \begin{itemize}
-    \item The interrupt handler is executed inside a thread.
-    \item Allows to block during the interrupt handler, which is often
-      needed for I2C/SPI devices as the interrupt handler needs to
-      communicate with them.
-    \item Allows to set a priority for the interrupt handler
-      execution, which is useful for real-time usage of Linux
-    \end{itemize}
-  \item \mint{c}+int request_threaded_irq(unsigned int irq,+
-    \mint{c}+irq_handler_t handler, irq_handler_t thread_fn,+
-    \mint{c}+unsigned long flags, const char *name, void *dev);+
-    \begin{itemize}
-    \item \code{handler}, ``hard IRQ'' handler
-    \item \code{thread_fn}, executed in a thread
-    \end{itemize}
+  \item The interrupt handler is executed inside a thread.
+  \item Allows to block during the interrupt handler, which is often
+        needed for I2C/SPI devices as the interrupt handler needs to
+        communicate with them.
+  \item Allows to set a priority for the interrupt handler
+        execution, which is useful for real-time usage of Linux
+  \end{itemize}
+  \begin{minted}{c}
+int devm_request_threaded_irq(
+    struct device *dev,
+    unsigned int irq,
+    irq_handler_t handler, irq_handler_t thread_fn
+    unsigned long flags, const char *name, void *dev);
+  \end{minted}
+  \begin{itemize}
+  \item \code{handler}, ``hard IRQ'' handler
+  \item \code{thread_fn}, executed in a thread
   \end{itemize}
 \end{frame}