[bootlin/training-materials updates] master: kernel: sleeping: Add two slides explaining the completion infrastructure (408bc909)

[Miquel Raynal]

Repository : https://github.com/bootlin/training-materials
On branch  : master
Link       : https://github.com/bootlin/training-materials/commit/408bc90918375d92f59e73d9f80ef936d4447578

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

commit 408bc90918375d92f59e73d9f80ef936d4447578
Author: Miquel Raynal <miquel.raynal at bootlin.com>
Date:   Tue Jun 22 20:36:23 2021 +0200

    kernel: sleeping: Add two slides explaining the completion infrastructure
    
    Completion objects are a direct child of the wait queue mechanism and
    are almost as widely used. They are also simpler to use, so add two
    slides explaining how to use them.
    
    Signed-off-by: Miquel Raynal <miquel.raynal at bootlin.com>


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

408bc90918375d92f59e73d9f80ef936d4447578
 .../kernel-driver-development-sleeping.tex         | 63 ++++++++++++++++++++--
 1 file changed, 59 insertions(+), 4 deletions(-)

diff --git a/slides/kernel-driver-development-sleeping/kernel-driver-development-sleeping.tex b/slides/kernel-driver-development-sleeping/kernel-driver-development-sleeping.tex
index b95ed897..aff7fead 100644
--- a/slides/kernel-driver-development-sleeping/kernel-driver-development-sleeping.tex
+++ b/slides/kernel-driver-development-sleeping/kernel-driver-development-sleeping.tex
@@ -10,7 +10,7 @@
 \end{frame}
 
 \begin{frame}[fragile]
-  \frametitle{How to sleep 1/3}
+  \frametitle{How to sleep with a wait queue 1/3}
   \begin{itemize}
   \item Must declare a wait queue, which will be used to store the list of threads
         waiting for an event
@@ -39,7 +39,7 @@ init_waitqueue_head(&dev->smi_busy_wait);
 \end{frame}
 
 \begin{frame}[fragile]
-  \frametitle{How to sleep 2/3}
+  \frametitle{How to sleep with a waitqueue 2/3}
   Several ways to make a kernel process sleep
   \begin{itemize}
   \item \mint{c}+void wait_event(queue, condition);+
@@ -63,7 +63,7 @@ init_waitqueue_head(&dev->smi_busy_wait);
 \end{frame}
 
 \begin{frame}[fragile]
-  \frametitle{How to sleep 3/3}
+  \frametitle{How to sleep with a waitqueue 3/3}
   \begin{itemize}
   \item \mint{c}+int wait_event_timeout(queue, condition, timeout);+
     \begin{itemize}
@@ -85,7 +85,7 @@ int wait_event_interruptible_timeout(queue, condition, timeout);
 \end{frame}
 
 \begin{frame}[fragile]
-\frametitle{How to sleep - Example}
+\frametitle{How to sleep with a waitqueue - Example}
 \begin{minted}{c}
 sig = wait_event_interruptible(ibmvtpm->wq,
                                !ibmvtpm->tpm_processing_cmd);
@@ -154,3 +154,58 @@ From \kfile{char/tpm/tpm_ibmvtpm.c}
        See \kfile{include/linux/wait.h} for implementation details.
   \end{columns}
 \end{frame}
+
+\begin{frame}[fragile]
+  \frametitle{How to sleep with completions 1/2}
+  \begin{itemize}
+  \item Use \kfunc{wait_for_completion} when no particular condition
+    must be enforced at the time of the wake-up
+    \begin{itemize}
+    \item Leverages the power of wait queues
+    \item Simplifies its use
+    \item Highly efficient using low level scheduler facilities
+    \end{itemize}
+  \item Preparation of the completion structure:
+    \begin{itemize}
+    \item Static declaration and initialization:
+      \mint{c}+DECLARE_COMPLETION(setup_done);+
+    \item Dynamic declaration:
+      \mint{c}+init_completion(&object->setup_done);+
+    \item The completion object should get a meaningful name (eg. not
+      just ``done'').
+    \end{itemize}
+  \item Ready to be used by signal consumers and providers as soon as
+    the completion object is initialized
+  \item See \kfile{include/linux/completion.h} for the full API
+  \item Internal documentation at \kdochtml{scheduler/completion.rst}
+  \end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+  \frametitle{How to sleep with completions 2/2}
+  \begin{itemize}
+  \item Enter a wait state with
+    \mint{c}+void wait_for_completion(struct completion *done)+
+    \begin{itemize}
+    \item All \kfunc{wait_event} flavors are also supported, such as:
+      \kfunc{wait_for_completion_timeout},
+      \kfunc{wait_for_completion_interruptible\{,_timeout\}},
+      \kfunc{wait_for_completion_killable\{,_timeout\}}, etc
+    \end {itemize}
+  \item Wake up consumers with
+    \mint{c}+void complete(struct completion *done)+
+    \begin{itemize}
+    \item Several calls to \kfunc{complete} are valid, they will wake up
+      the same number of threads waiting on this object (acts as a FIFO).
+    \item A single \kfunc{complete_all} call would wake up all present and
+      future threads waiting on this completion object
+    \end {itemize}
+  \item Reset the counter with
+    \mint{c}+void reinit_completion(struct completion *done)+
+    \begin{itemize}
+    \item Resets the number of ``done'' completions still pending
+    \item Mind not to call \kfunc{init_completion} twice, which could
+      confuse the enqueued tasks
+    \end{itemize}
+  \end{itemize}
+\end{frame}