[BL training-materials-updates] kernel labs: use Elixir links
Michael Opdenacker
michael.opdenacker at bootlin.com
Sat Nov 24 17:46:14 CET 2018
Repository : git://git.free-electrons.com/training-materials.git
On branch : master
Link : http://git.free-electrons.com/training-materials/commit/?id=41e1be72bb5f126de5df62e0aa2dfb606c28eef5
>---------------------------------------------------------------
commit 41e1be72bb5f126de5df62e0aa2dfb606c28eef5
Author: Michael Opdenacker <michael.opdenacker at bootlin.com>
Date: Sat Nov 24 17:46:14 2018 +0100
kernel labs: use Elixir links
Signed-off-by: Michael Opdenacker <michael.opdenacker at bootlin.com>
>---------------------------------------------------------------
41e1be72bb5f126de5df62e0aa2dfb606c28eef5
labs/kernel-debugging/kernel-debugging.tex | 4 ++--
.../kernel-i2c-communication.tex | 14 +++++++-------
.../kernel-i2c-device-model.tex | 4 ++--
.../kernel-i2c-input-interface.tex | 22 +++++++++++-----------
labs/kernel-module-simple/kernel-module-simple.tex | 4 ++--
.../kernel-serial-interrupt.tex | 10 +++++-----
labs/kernel-serial-iomem/kernel-serial-iomem.tex | 8 ++++----
labs/kernel-serial-output/kernel-serial-output.tex | 14 +++++++-------
.../kernel-sources-exploring.tex | 4 ++--
9 files changed, 42 insertions(+), 42 deletions(-)
diff --git a/labs/kernel-debugging/kernel-debugging.tex b/labs/kernel-debugging/kernel-debugging.tex
index 27a459d..111e592 100644
--- a/labs/kernel-debugging/kernel-debugging.tex
+++ b/labs/kernel-debugging/kernel-debugging.tex
@@ -6,9 +6,9 @@ In this lab, we will continue to work on the code of our serial driver.
\section{pr\_debug() and dynamic debugging}
-Add a \code{pr_debug()} call in the \code{write()} operation that shows
+Add a \kfunc{pr_debug} call in the \code{write()} operation that shows
each character being written (or its hexadecimal representation) and
-add a similar \code{pr_debug()} call in your interrupt handler to show
+add a similar \kfunc{pr_debug} call in your interrupt handler to show
each character being received.
Check what happens with your module. Do you see the debugging messages
diff --git a/labs/kernel-i2c-communication/kernel-i2c-communication.tex b/labs/kernel-i2c-communication/kernel-i2c-communication.tex
index 0c05cb8..217ebdc 100644
--- a/labs/kernel-i2c-communication/kernel-i2c-communication.tex
+++ b/labs/kernel-i2c-communication/kernel-i2c-communication.tex
@@ -18,7 +18,7 @@ compiling (stay in the \code{nunchuk} branch), and in
\section{Remove debugging messages}
Now that we have checked that the \code{probe()} and \code{remove()} functions
-are called, remove the \code{pr_info()} messages that you added to
+are called, remove the \kfunc{pr_info} messages that you added to
trace the execution of these functions.
\section{Find pin muxing configuration information for i2c1}
@@ -175,8 +175,8 @@ sure i2c communication works as expected.
In the probe routine (run every time a matching device is found):
\begin{enumerate}
-\item Using the I2C raw API (\code{i2c_master_send()} and
- \code{i2c_master_recv()}), send two bytes to the
+\item Using the I2C raw API (\kfunc{i2c_master_send} and
+ \kfunc{i2c_master_recv}), send two bytes to the
device: \code{0xf0} and \code{0x55}\footnote{
The I2C messages to communicate with a wiimote
extension are in the form: \code{<i2c_address> <register> }
@@ -197,7 +197,7 @@ In the probe routine (run every time a matching device is found):
using. This could reveal communication issues. Using Elixir, find
examples of how to handle failures properly using the same
function.
-\item Let the CPU wait for 1 ms by using the \code{msleep()} routine.
+\item Let the CPU wait for 1 ms by using the \kfunc{msleep} routine.
You may need to use Elixir again to find the right C headers to
include.
\item In the same way, send the \code{0xfb} and \code{0x00} bytes now.
@@ -220,8 +220,8 @@ In this function:
\begin{enumerate}
\item Start by putting a \code{10 ms} delay by calling the
- \code{msleep()} routine\footnote{\code{msleep()} is nicer
- than \code{mdelay()} because it is not making an active wait, and
+ \kfunc{msleep} routine\footnote{\kfunc{msleep} is nicer
+ than \kfunc{mdelay} because it is not making an active wait, and
instead lets the CPU run other tasks in the meantime.}. That's needed
to add time between the previous i2c operation and the next one.
\item Write \code{0x00} to the bus. That will allow us to read
@@ -251,7 +251,7 @@ As explained on
Using boolean operators, write code that initializes a \code{zpressed}
integer variable, which value is \code{1} when the \code{Z} button is
pressed, and \code{0} otherwise. Create a similar \code{cpressed}
-variable for the \code{C} button\footnote{You may use the \code{BIT()}
+variable for the \code{C} button\footnote{You may use the \kfunc{BIT}
macro, which will make your life easier. See Elixir for details.}.
The last thing is to test the states of these new variables at the end
diff --git a/labs/kernel-i2c-device-model/kernel-i2c-device-model.tex b/labs/kernel-i2c-device-model/kernel-i2c-device-model.tex
index bdf0560..6b88c29 100644
--- a/labs/kernel-i2c-device-model/kernel-i2c-device-model.tex
+++ b/labs/kernel-i2c-device-model/kernel-i2c-device-model.tex
@@ -159,9 +159,9 @@ Relying on explanations given during the lectures, fill the
\begin{itemize}
\item \code{probe()} and \code{remove()} functions that will
be called when a nunchuk is found.
- For the moment, just put a call to \code{pr_info()} inside
+ For the moment, just put a call to \kfunc{pr_info} inside
to confirm that these function are called.
-\item Initialize an \code{i2c_driver} structure, and register
+\item Initialize a \ksym{i2c_driver} structure, and register
the i2c driver using it. Make sure that you use
a \code{compatible} property that matches the one in the
Device Tree.
diff --git a/labs/kernel-i2c-input-interface/kernel-i2c-input-interface.tex b/labs/kernel-i2c-input-interface/kernel-i2c-input-interface.tex
index 1daed52..7303dc8 100644
--- a/labs/kernel-i2c-input-interface/kernel-i2c-input-interface.tex
+++ b/labs/kernel-i2c-input-interface/kernel-i2c-input-interface.tex
@@ -33,19 +33,19 @@ The first thing to do is to add an input device to the system. Here are
the steps to do it:
\begin{itemize}
-\item Declare a pointer to an \code{input_polled_dev} structure in the
+\item Declare a pointer to an \ksym{input_polled_dev} structure in the
\code{probe} routine. You can call it \code{polled_input}.
You can't use a global variable because your driver needs to be
able to support multiple devices.
\item Allocate such a structure in the same function, using the
- \code{devm_input_allocate_polled_device()} function.
-\item Also declare a pointer to an \code{input_dev} structure. You can
+ \kfunc{devm_input_allocate_polled_device} function.
+\item Also declare a pointer to an \ksym{input_dev} structure. You can
call it \code{input}. We won't need to allocate it, because it
- is already part of the \code{input_polled_dev} structure,
+ is already part of the \ksym{input_polled_dev} structure,
and allocated at the same time.
We will use this as a shortcut to keep the code simple.
\item Still in the \code{probe()} function, add the input device to
- the system by calling \code{input_register_polled_device()};
+ the system by calling \kfunc{input_register_polled_device};
\end{itemize}
At this stage, first make sure that your module compiles well (add
@@ -62,7 +62,7 @@ situations properly.
\item In our case, we only allocated resources with \code{devm_}
functions. Thanks to this, in case of failure, all the
corresponding allocations are automatically released
- before destroying the \code{device} structure for each
+ before destroying the \ksym{device} structure for each
device. This greatly simplifies our error management code!
\end{itemize}
@@ -73,7 +73,7 @@ and registered in the \code{probe()} routine.
Fortunately, in our case, there's nothing to do, as everything
was allocated with \code{devm_} functions. Even the unregistration
-of the \code{input_polled_dev} structure is automated.
+of the \ksym{input_polled_dev} structure is automated.
Recompile your module, and load it and remove it multiple times, to
make sure that everything is properly registered and automatically
@@ -81,7 +81,7 @@ unregistered.
\section{Add proper input device registration information}
-We actually need to add more information to the input structure before
+We actually need to add more information to the \ksym{input} structure before
registering it. That's why we are getting the below warnings:
\begin{verbatim}
@@ -104,11 +104,11 @@ It's time to implement the routine which will poll the nunchuk registers
at a regular interval.
Create a \code{nunchuk_poll()} function with the right prototype (find
-it by looking at the definition of the \code{input_polled_dev} structure.
+it by looking at the definition of the \ksym{input_polled_dev} structure.
In this function, you will have to read the nunchuk registers. However,
as you can see, the prototype of the \code{poll()} routine doesn't
-carry any information about the \code{i2c_client} structure you will
+carry any information about the \ksym{i2c_client} structure you will
need to communicate with the device. That's normal as the input
subsystem is generic, and can't be bound to any specific bus.
@@ -164,7 +164,7 @@ don't want to enable a device with incomplete information or when it is
not completely yet (there could be race conditions).
First, add lines retrieving the I2C physical device from the
-\code{input_polled_dev} structure. That's where you will need your
+\ksym{input_polled_dev} structure. That's where you will need your
private \code{nunchuk} structure.
Now that you have a handle on the I2C physical device, you can move the
diff --git a/labs/kernel-module-simple/kernel-module-simple.tex b/labs/kernel-module-simple/kernel-module-simple.tex
index 3650ead..a729ea8 100644
--- a/labs/kernel-module-simple/kernel-module-simple.tex
+++ b/labs/kernel-module-simple/kernel-module-simple.tex
@@ -68,10 +68,10 @@ parameter into account when you load it.
Improve your module, so that when you unload it, it tells you how many
seconds elapsed since you loaded it. You can use the
-\code{do_gettimeofday()} function to achieve this.
+\kfunc{do_gettimeofday} function to achieve this.
You may search for other drivers in the kernel sources using the
-\code{do_gettimeofday()} function. Looking for other examples always helps!
+\kfunc{do_gettimeofday} function. Looking for other examples always helps!
\section{Following Linux coding standards}
diff --git a/labs/kernel-serial-interrupt/kernel-serial-interrupt.tex b/labs/kernel-serial-interrupt/kernel-serial-interrupt.tex
index d9cbfd6..b6f086a 100644
--- a/labs/kernel-serial-interrupt/kernel-serial-interrupt.tex
+++ b/labs/kernel-serial-interrupt/kernel-serial-interrupt.tex
@@ -41,13 +41,13 @@ struct serial_dev {
};
\end{verbatim}
-Now, to retrieve the IRQ number to be used with \code{devm_request_irq()}:
+Now, to retrieve the IRQ number to be used with \kfunc{devm_request_irq}:
\begin{verbatim}
dev->irq = platform_get_irq(pdev, 0);
\end{verbatim}
-Then, pass the interrupt number to \code{devm_request_irq()} along
+Then, pass the interrupt number to \kfunc{devm_request_irq} along
with the interrupt handler to register your interrupt in the kernel.
Then, in the interrupt handler, just print a message and return
@@ -133,16 +133,16 @@ available for reading (i.e, if \code{serial_buf_wr} is equal to
To do so, add a wait queue to our \code{serial_dev} structure,
named for example \code{serial_wait}. In the \code{read()} function,
-keep things simple by directly using \code{wait_event_interruptible()}
+keep things simple by directly using \kfunc{wait_event_interruptible}
right from the start, to wait until \code{serial_buf_wr}
is different from \code{serial_buf_rd}\footnote{A single test in the
-\code{wait_event_interruptible()} function is sufficient. If the
+\kfunc{wait_event_interruptible} function is sufficient. If the
condition is met, you don't go to sleep and read one character right away.
Otherwise, when you wake up, you can proceed to the reading part.}.
Last but not least, in the interrupt handler,
after storing the received characters in the circular buffer, use
-\code{wake_up()} to wake up all processes waiting on the wait queue.
+\kfunc{wake_up} to wake up all processes waiting on the wait queue.
Compile and load your driver. Run \code{cat /dev/serial-48024000}
on the target, and then in \code{picocom} on the development
diff --git a/labs/kernel-serial-iomem/kernel-serial-iomem.tex b/labs/kernel-serial-iomem/kernel-serial-iomem.tex
index f43d53a..2cc5d1c 100644
--- a/labs/kernel-serial-iomem/kernel-serial-iomem.tex
+++ b/labs/kernel-serial-iomem/kernel-serial-iomem.tex
@@ -123,7 +123,7 @@ structure that will hold device specific information and help
keeping pointers between logical and physical devices.
As the first thing to store will be the base virtual address for
-each device (obtained through \code{ioremap()}), let's declare this
+each device (obtained through \kfunc{ioremap}), let's declare this
structure as follows:
\begin{verbatim}
@@ -133,7 +133,7 @@ struct serial_dev {
\end{verbatim}
The first thing to do is allocate such a structure at the beginning
-of the \code{probe()} routine. Let's do it with the \code{devm_kzalloc}
+of the \code{probe()} routine. Let's do it with the \kfunc{devm_kzalloc}
function again as in the previous lab. Again, resource deallocation is
automatically taken care of when we use the \code{devm_} functions.
@@ -186,7 +186,7 @@ completely ready to use and we have to multiply them by 4 for OMAP SoCs.
Create a similar \code{reg_write()} routine, writing an unsigned integer
value at a given integer offset (don't forget to multiply it by 4) from
the device base virtual address. The following code samples are using
-the \code{writel()} convention of passing the value first, then the
+the \kfunc{writel} convention of passing the value first, then the
offset. Your prototype should look like:
\begin{verbatim}
static void reg_write(struct serial_dev *dev, int val, int off);
@@ -241,7 +241,7 @@ this character to the serial port, using the following steps:
\begin{enumerate}
\item Wait until the \code{UART_LSR_THRE} bit gets set in the
\code{UART_LSR} register. You can busy-wait for this condition to happen.
- In the busy-wait loop, you can call the \code{cpu_relax()} kernel function
+ In the busy-wait loop, you can call the \kfunc{cpu_relax} kernel function
to ensure the compiler won't optimise away this loop.
\item Write the character to the \code{UART_TX} register.
\end{enumerate}
diff --git a/labs/kernel-serial-output/kernel-serial-output.tex b/labs/kernel-serial-output/kernel-serial-output.tex
index 6a65540..562e433 100644
--- a/labs/kernel-serial-output/kernel-serial-output.tex
+++ b/labs/kernel-serial-output/kernel-serial-output.tex
@@ -35,11 +35,11 @@ The first thing to do is to create:
body so far, to signal that there is something wrong with this
function so far.
\item Similarly, an \code{serial_read()} read file operation stub.
-\item A \code{file_operations} structure declaring these file
+\item A \ksym{file_operations} structure declaring these file
operations.
\end{itemize}
-The next step is to create a \code{miscdevice} structure and initialize
+The next step is to create a \ksym{miscdevice} structure and initialize
it. However, we are facing the same usual constraint to handle multiple
devices. Like in the Nunchuk driver, we have to add such a structure
to our device specific private data structure:
@@ -53,20 +53,20 @@ struct serial_dev {
To be able to access our private data structure in other parts of the
driver, you need to attach it to the \code{pdev} structure using the
-\code{platform_set_drvdata()} function. Look for examples in the
+\kfunc{platform_set_drvdata} function. Look for examples in the
source code to find out how to do it.
Now, at the end of the \code{probe()} routine, when the device is fully ready
-to work, you can now initialize the \code{miscdevice} structure
+to work, you can now initialize the \ksym{miscdevice} structure
for each found device:
\begin{itemize}
\item To get an automatically assigned minor number.
\item To specify a name for the device file in {\em devtmpfs}. We
propose to use {\tt devm\_kasprintf(\&pdev->dev, GFP\_KERNEL,
- "serial-\%x", res->start)}. \code{devm_kasprintf()} allocates a
- buffer and runs \code{ksprintf()} to fill its contents.
-\item To pass the file operations structure that you defined.
+ "serial-\%x", res->start)}. \kfunc{devm_kasprintf} allocates a
+ buffer and runs \kfunc{kasprintf} to fill its contents.
+\item To pass the \ksym{file_operations} structure that you defined.
\end{itemize}
See the lectures for details if needed!
diff --git a/labs/kernel-sources-exploring/kernel-sources-exploring.tex b/labs/kernel-sources-exploring/kernel-sources-exploring.tex
index 40fe49c..3c8af77 100644
--- a/labs/kernel-sources-exploring/kernel-sources-exploring.tex
+++ b/labs/kernel-sources-exploring/kernel-sources-exploring.tex
@@ -50,7 +50,7 @@ exploring the kernel sources.
files in \code{logo} in their name. It's an
opportunity to practise with the \code{find} command.}.
\item Find who the maintainer of the MVNETA network driver is.
-\item Find the declaration of the \code{platform_device_register()} function.
+\item Find the declaration of the \kfunc{platform_device_register} function.
\end{enumerate}
Tip: if you need the \code{grep} command, we advise you to use \code{git
@@ -69,5 +69,5 @@ and choose the Linux version closest to yours.
If you don't have Internet access, you can use \code{cscope} instead.
As in the previous section, use this tool to find where
-the \code{platform_device_register()} function is declared, implemented and
+the \kfunc{platform_device_register} function is declared, implemented and
even used.
More information about the training-materials-updates
mailing list