[bootlin/training-materials updates] master: sysdev/beagleplay: add block filesystems lab (f6514e85)

[Michael Opdenacker]

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

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

commit f6514e85d292e9ebf0dbda01dcdd9bafcfa9599f
Author: Clément Ramirez <clement.ramirez at bootlin.com>
Date:   Wed Jul 19 17:56:07 2023 +0200

    sysdev/beagleplay: add block filesystems lab


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

f6514e85d292e9ebf0dbda01dcdd9bafcfa9599f
 .../sysdev-block-filesystems-beagleplay.tex        | 172 +++++++++++++++++++++
 mk/embedded-linux-beagleplay.mk                    |   1 +
 2 files changed, 173 insertions(+)

diff --git a/labs/sysdev-block-filesystems-beagleplay/sysdev-block-filesystems-beagleplay.tex b/labs/sysdev-block-filesystems-beagleplay/sysdev-block-filesystems-beagleplay.tex
new file mode 100644
index 00000000..6dd5676f
--- /dev/null
+++ b/labs/sysdev-block-filesystems-beagleplay/sysdev-block-filesystems-beagleplay.tex
@@ -0,0 +1,172 @@
+\subchapter{Filesystems - Block file systems}{Objective: configure and
+  boot an embedded Linux system relying on block storage}
+
+After this lab, you will be able to:
+\begin{itemize}
+\item Produce file system images.
+\item Configure the kernel to use these file systems
+\item Use the tmpfs file system to store temporary files
+\item Load the kernel and DTB from a EXT4 partition
+\end{itemize}
+
+\section{Goals}
+
+After doing the {\em A tiny embedded system} lab, we are going to copy
+the filesystem contents to the SD card. The storage will be
+split into several partitions, and your board will boot
+on an root filesystem on this SD card, without using NFS anymore.
+
+\section{Setup}
+
+Throughout this lab, we will continue to use the root filesystem we
+have created in the \code{$HOME/__SESSION_NAME__-labs/tinysystem/nfsroot}
+directory, which we will progressively adapt to use block filesystems.
+
+\section{Filesystem support in the kernel}
+
+Recompile your kernel with support for SquashFS and ext4\footnote{Basic
+configuration options for these filesystems will be sufficient. No need
+for things like extended attributes.}.
+
+Update your kernel image in the boot partition.
+
+Boot your board with this new kernel and on the NFS filesystem you
+used in this previous lab.
+
+Now, check the contents of \code{/proc/filesystems}. You should see
+ that ext4 and SquashFS are now supported.
+
+\section{Add partitions to the SD card}
+
+Plug the SD card in your workstation. If partitions are mounted,
+unmount them:
+
+\bashcmd{$ sudo umount /dev/mmcblk0p*}
+
+Using \code{fdisk /dev/mmcblk0}, add two partitions, starting from the beginning
+of the remaining space, with the following properties:
+
+\begin{itemize}
+\item A third primary partition, 100 MB big, for the root filesystem
+\item A fourth primary partition, that fills the rest of the SD card, that will be
+  used for the data filesystem
+\end{itemize}
+
+Save and exit when you are done.
+
+\section{Data partition on the SD card}
+
+Using the \code{mkfs.ext4} create a journaled file system on the
+fourth partition of the SD card:
+
+\bashcmd{$ sudo mkfs.ext4 -L data -E nodiscard /dev/mmcblk0p4}
+
+\begin{itemize}
+\item \code{-L} assigns a volume name to the partition
+\item \code{-E nodiscard} disables bad block discarding. While this
+      should be a useful option for cards with bad blocks, skipping
+      this step saves long minutes in SD cards.
+\end{itemize}
+
+Now, mount this new partition and move the contents of the
+\code{/www/upload/files} directory (in your target root filesystem) into
+it. The goal is to use the data partition of the SD card as the storage
+for the uploaded images.
+
+Insert the SD card in your board and boot. You should see the
+partitions in \code{/proc/partitions}.
+
+Mount this data partition on \code{/www/upload/files}.
+
+Once this works, modify the startup scripts in your root filesystem
+to do it automatically at boot time.
+
+Reboot your target system and with the \code{mount} command, check that
+\code{/www/upload/files} is now a mount point for the last SD card
+partition. Also make sure that you can still upload new images, and
+that these images are listed in the web interface.
+
+\section{Adding a tmpfs partition for log files}
+
+For the moment, the upload script was storing its log file in
+\code{/www/upload/files/upload.log}. To avoid seeing this log file in
+the directory containing uploaded files, let's store it in
+\code{/var/log} instead.
+
+Add the \code{/var/log/} directory to your root filesystem and modify
+the startup scripts to mount a \code{tmpfs} filesystem on this
+directory. You can test your \code{tmpfs} mount command line on the
+system before adding it to the startup script, in order to be sure
+that it works properly.
+
+Modify the \code{www/cgi-bin/upload.cfg} configuration file to store
+the log file in \code{/var/log/upload.log}. You will lose your log
+file each time you reboot your system, but that's OK in our
+system. That's what \code{tmpfs} is for: temporary data that you don't need
+to keep across system reboots.
+
+Reboot your system and check that it works as expected.
+
+\section{Making a SquashFS image}
+
+We are going to store the root filesystem in a SquashFS filesystem in
+the third partition of the SD card.
+
+In order to create SquashFS images on your host, you need to install
+the \code{squashfs-tools} package. Now create a SquashFS image of your
+NFS root directory.
+
+Finally, using the \code{dd} command, copy the file system image to
+the third partition of the SD card.
+
+\section{Booting on the SquashFS partition}
+
+In the U-boot shell, configure the kernel command line to use the
+third partition of the SD card as the root file system. Also add the
+\code{rootwait} boot argument, to wait for the SD card to be properly
+initialized before trying to mount the root filesystem. Since the SD
+cards are detected asynchronously by the kernel, the kernel might try
+to mount the root filesystem too early without \code{rootwait}.
+
+Check that your system still works.
+
+\section{Loading the kernel and DTB from the SD card}
+
+In order to let the kernel boot on the board autonomously, we can
+copy the kernel image and DTB in the boot partition we created
+previously.
+
+Insert the SD card in your PC, it will get auto-mounted. Copy the
+kernel and device tree to the \code{env} partition.
+
+Insert the SD card back in the board and reset it. You should now be
+able to load the DTB and kernel image from the SD card and boot with:
+
+\begin{ubootinput}
+=> load mmc 1:2 %\zimageboardaddr% Image.gz
+=> load mmc 1:2 %\dtbboardaddr% %\dtname%-custom.dtb
+=> booti %\zimageboardaddr% - %\dtbboardaddr%
+\end{ubootinput}
+
+You are now ready to modify \code{bootcmd} to boot the board
+from SD card. But first, save the settings for booting from
+\code{tftp}:
+
+\begin{ubootinput}
+=> setenv bootcmdtftp %\$%{bootcmd}
+\end{ubootinput}
+
+This will be useful to switch back to \code{tftp} booting mode
+later in the labs.
+
+Finally, using \code{editenv bootcmd}, adjust \code{bootcmd} so that
+the board starts using the kernel from the SD card.
+
+Now, reset the board to check that it boots in the same way from the
+SD card.
+
+Now, the whole system (bootloader, kernel and filesystems) is
+stored on the SD card. That's very useful for product demos, for
+examples. You can switch demos by switching SD cards, and the
+system depends on nothing else. In particular, no networking is
+necessary.
diff --git a/mk/embedded-linux-beagleplay.mk b/mk/embedded-linux-beagleplay.mk
index f172e5b5..4ed23093 100644
--- a/mk/embedded-linux-beagleplay.mk
+++ b/mk/embedded-linux-beagleplay.mk
@@ -56,3 +56,4 @@ EMBEDDED_LINUX_BEAGLEPLAY_LABS = setup \
 		sysdev-kernel-cross-compiling \
 		sysdev-tinysystem \
 		sysdev-accessing-hardware-beagleplay \
+		sysdev-block-filesystems-beagleplay \