Merge pull request #351 from Jordymalone/improve-latex

jserv · web-flow · commit f2e09d3d5f4f · 2025-09-29T00:47:51.000+08:00
Improve LaTeX source maintainability
diff --git a/lkmpg.tex b/lkmpg.tex
@@ -65,18 +65,23 @@ \section{Introduction}
 \label{sec:introduction}
 The Linux Kernel Module Programming Guide is a free book; you may reproduce or modify it under the terms of the \href{https://opensource.org/licenses/OSL-3.0}{Open Software License}, version 3.0.
 
-This book is distributed in the hope that it would be useful, but without any warranty, without even the implied warranty of merchantability or fitness for a particular purpose.
+This book is distributed in the hope that it would be useful, but without any warranty,
+without even the implied warranty of merchantability or fitness for a particular purpose.
 
-The author encourages wide distribution of this book for personal or commercial use, provided the above copyright notice remains intact and the method adheres to the provisions of the \href{https://opensource.org/licenses/OSL-3.0}{Open Software License}.
-In summary, you may copy and distribute this book free of charge or for a profit. No explicit permission is required from the author for reproduction of this book in any medium, physical or electronic.
+The author encourages wide distribution of this book for personal or commercial use,
+provided the above copyright notice remains intact and the method adheres to the provisions of the \href{https://opensource.org/licenses/OSL-3.0}{Open Software License}.
+In summary, you may copy and distribute this book free of charge or for a profit.
+No explicit permission is required from the author for reproduction of this book in any medium, physical or electronic.
 
 Derivative works and translations of this document must be placed under the Open Software License, and the original copyright notice must remain intact.
 If you have contributed new material to this book, you must make the material and source code available for your revisions.
 Please make revisions and updates available directly to the document maintainer, Jim Huang <jserv@ccns.ncku.edu.tw>.
 This will allow for the merging of updates and provide consistent revisions to the Linux community.
 
-If you publish or distribute this book commercially, donations, royalties, or printed copies are greatly appreciated by the author and the \href{https://tldp.org/}{Linux Documentation Project} (LDP).
-Contributing in this way shows your support for free software and the LDP. If you have questions or comments, please contact the address above.
+If you publish or distribute this book commercially, donations, royalties,
+or printed copies are greatly appreciated by the author and the \href{https://tldp.org/}{Linux Documentation Project} (LDP).
+Contributing in this way shows your support for free software and the LDP.
+If you have questions or comments, please contact the address above.
 
 \subsection{Authorship}
 \label{sec:authorship}
@@ -536,7 +541,8 @@ \subsection{Passing Command Line Arguments to a Module}
 The example code should clear up my admittedly lousy explanation.
 
 The \cpp|module_param()| macro takes 3 arguments: the name of the variable, its type and permissions for the corresponding file in sysfs.
-Integer types can be signed as usual or unsigned. If you would like to use arrays of integers or strings, see \cpp|module_param_array()| and \cpp|module_param_string()|.
+Integer types can be signed as usual or unsigned. If you would like to use arrays of integers or strings,
+see \cpp|module_param_array()| and \cpp|module_param_string()|.
 
 \begin{code}
 int myint = 3;
@@ -545,7 +551,8 @@ \subsection{Passing Command Line Arguments to a Module}
 
 Arrays are supported too, but things are a bit different now than they were in the olden days.
 To keep track of the number of parameters, you need to pass a pointer to a count variable as the third parameter.
-At your option, you could also ignore the count and pass \cpp|NULL| instead. We show both possibilities here:
+At your option, you could also ignore the count and pass \cpp|NULL| instead.
+We show both possibilities here:
 
 \begin{code}
 int myintarray[2];
@@ -557,7 +564,8 @@ \subsection{Passing Command Line Arguments to a Module}
 \end{code}
 
 A good use for this is to have the module variable's default values set, like a port or IO address.
-If the variables contain the default values, then perform autodetection (explained elsewhere). Otherwise, keep the current value.
+If the variables contain the default values, then perform autodetection (explained elsewhere).
+Otherwise, keep the current value.
 This will be made clear later on.
 
 Lastly, there is a macro function, \cpp|MODULE_PARM_DESC()|, that is used to document arguments that the module can take.
@@ -635,16 +643,22 @@ \subsection{Modules Spanning Multiple Files}
 
 \subsection{Building modules for a precompiled kernel}
 \label{sec:precompiled}
-Obviously, we strongly suggest you to recompile your kernel, so that you can enable a number of useful debugging features, such as forced module unloading (\cpp|MODULE_FORCE_UNLOAD|): when this option is enabled, you can force the kernel to unload a module even when it believes it is unsafe, via a \sh|sudo rmmod -f module| command.
+% TODO: Recent Linux kernel images shipped with distributions should already have sufficient debugging features enabled for LKMPG.
+Obviously, we strongly suggest you to recompile your kernel, so that you can enable a number of useful debugging features,
+such as forced module unloading (\cpp|MODULE_FORCE_UNLOAD|): when this option is enabled,
+you can force the kernel to unload a module even when it believes it is unsafe, via a \sh|sudo rmmod -f module| command.
 This option can save you a lot of time and a number of reboots during the development of a module.
 If you do not want to recompile your kernel then you should consider running the examples within a test distribution on a virtual machine.
 If you mess anything up then you can easily reboot or restore the virtual machine (VM).
 
-There are a number of cases in which you may want to load your module into a precompiled running kernel, such as the ones shipped with common Linux distributions, or a kernel you have compiled in the past.
-In certain circumstances you could require to compile and insert a module into a running kernel which you are not allowed to recompile, or on a machine that you prefer not to reboot.
+There are a number of cases in which you may want to load your module into a precompiled running kernel,
+such as the ones shipped with common Linux distributions, or a kernel you have compiled in the past.
+In certain circumstances you could require to compile and insert a module into a running kernel which you are not allowed to recompile,
+or on a machine that you prefer not to reboot.
 If you can't think of a case that will force you to use modules for a precompiled kernel you might want to skip this and treat the rest of this chapter as a big footnote.
 
-Now, if you just install a kernel source tree, use it to compile your kernel module and you try to insert your module into the kernel, in most cases you would obtain an error as follows:
+Now, if you just install a kernel source tree, use it to compile your kernel module and you try to insert your module into the kernel,
+in most cases you would obtain an error as follows:
 
 \begin{verbatim}
 insmod: ERROR: could not insert module poet.ko: Invalid module format
