boot-time-build-kernel-and-start-system.tex

\subchapter{Build the kernel and boot the system}{Objective: configure, compile and install the
kernel, install the root file system and see the full system in action!}

At the end of the lab, you'll have your system completely up and
running.

\section{Setup}

Go to the \code{~/boot-time-labs/kernel/linux/} directory and install a
package to we will need to compile the Linux kernel:

\begin{verbatim}
sudo apt install libssl-dev
\end{verbatim}

First let's get the latest updates to the remote \code{stable} tree
(that's needed if you started from a ready made archive of the Linux git
repository):

\begin{verbatim}
git fetch stable
\end{verbatim}

First, let's get the list of branches on our \code{stable} remote tree:

\begin{verbatim}
git branch -a
\end{verbatim}

As we will do our labs with the Linux 5.11 stable branch, the remote branch
we are interested in is \code{remotes/stable/linux-5.11.y}.

First, open the \code{Makefile} file just to check the Linux kernel
version that you currently have.

Now, let's create a local branch starting from that remote branch:
\begin{verbatim}
git checkout -b 5.11-beaglecam stable/linux-5.11.y
\end{verbatim}

This local branch will allow us to keep our modifications to the Linux
kernel to support the 4.3" LCD cape that we're using.

Open \code{Makefile} again and make sure you now have a 5.11.<n> version.

\section{Compiling environment}

You need the same \code{PATH} and \code{CROSS_COMPILE} environment
variables as when you compiled U-Boot, plus the \code{ARCH} one that
corresponds to the target architecture.

\begin{verbatim}
export CROSS_COMPILE=arm-linux-gnueabihf-
export ARCH=arm
\end{verbatim}

\section{Adding support for the 4.3" LCD cape}

To support using the 4.3" LCD cape, all we need to do is declare and
configure the devices on this cape. This is typically done by
customizing the board's {\em Device Tree} or by adding a {\em Device
Tree Overlay}.

So, to avoid messing with the standard DTS for our board, let's use a
such a customized device tree through a separate file:

\begin{verbatim}
cp ~/boot-time-labs/kernel/data/am335x-boneblack-lcd43.dts arch/arm/boot/dts/
\end{verbatim}

You now have to modify \code{arch/arm/boot/dts/Makefile} so that
the new DTS file gets compiled too.

\section{Configuring the Linux kernel}

First, lets pick the default kernel configuration for boards with a TI
OMAP or AMxxxx SoC:

\begin{verbatim}
make help | grep omap
\end{verbatim}

What we need is the configuration for OMAP2 and later SoCs:
\begin{verbatim}
make omap2plus_defconfig
\end{verbatim}

Let's run \code{make menuconfig} or \code{make xconfig} and select the
below options. Use the search capability of such configuration
interfaces to find the corresponding parameters (remove \code{CONFIG_}
when you search.

To enable support for the framebuffer and the PWM backlight:
\begin{itemize}
\item \kconfigval{CONFIG_PWM_TIEHRPWM}{y}
\item \kconfigval{CONFIG_FB_SIMPLE}{y}
\item \kconfigval{CONFIG_BACKLIGHT_PWM}{y}
\item \kconfigval{CONFIG_DRM}{y}
\item \kconfigval{CONFIG_DRM_TILCDC}{y}
\item \kconfigval{CONFIG_DRM_TI_TFP410}{y}
\end{itemize}

For USB support:
\begin{itemize}
\item \kconfigval{CONFIG_USB}{y}
\item \kconfigval{CONFIG_USB_MUSB_HDRC}{y}
\item \kconfigval{CONFIG_USB_MUSB_DSPS}{y}
\item \kconfigval{CONFIG_MUSB_PIO_ONLY}{y}
\item \kconfigval{CONFIG_USB_GADGET}{y}\\
      You may wonder why we need this while we're not using USB gadget
      at all. At least in the 5.1 kernel, this setting was required to get some
      of the USB host functionality we needed.
\item \kconfigval{CONFIG_NOP_USB_XCEIV}{y}
\item \kconfigval{CONFIG_AM335X_PHY_USB}{y}
\item \kconfigval{CONFIG_USB_GPIO_VBUS}{y}
\item \kconfigval{CONFIG_USB_GADGET_VBUS_DRAW}{500}
\item \kconfigval{CONFIG_USB_CONFIGFS_F_UVC}{y}
\end{itemize}

For the webcam
\begin{itemize}
\item \kconfigval{CONFIG_MEDIA_SUPPORT}{y} 
\item \kconfigval{CONFIG_MEDIA_USB_SUPPORT}{y}
\item \kconfigval{CONFIG_VIDEO_DEV}{y}
\item \kconfigval{CONFIG_USB_VIDEO_CLASS}{y}
\end{itemize}

For your convenience, of if you screw up your settings in a later lab,
you can also use a reference configuration file found in
\code{boot-time-labs/kernel/data}.

\section{Compiling the kernel}

To compile the device tree, just run:
\begin{verbatim}
make dtbs
\end{verbatim}

To compile the kernel, just run:
\begin{verbatim}
make -j 8 zImage
\end{verbatim}

Note that the default \code{make} target would have worked too, but with
just \code{zImage}, we avoid compiling many modules that are configured
in the default configuration. This saves quite a lot of time!

At the end, copy the kernel binary and DTB to the SD card's boot
partition:

\begin{verbatim}
cp arch/arm/boot/zImage /media/$USER/boot/
cp arch/arm/boot/dts/am335x-boneblack-lcd43.dtb /media/$USER/boot/dtb
\end{verbatim}

\section{Installing the root filesystem}

We are also ready to install the root filesystem. Still with the SD card
connected to your workstation:

\begin{verbatim}
cd ~/boot-time-labs/rootfs/buildroot
rm -rf /media/$USER/rootfs/*
sudo tar -C /media/$USER/rootfs/ -xf output/images/rootfs.tar
sudo umount /media/$USER/rootfs
sudo umount /media/$USER/boot
\end{verbatim}

Then insert the SD card in the board's slot.

\section{Bootloader configuration}

Back to the serial console for your board, let's define the default boot
sequence, to load the kernel and DTB from the external SD card:

{\footnotesize
\begin{verbatim}
setenv bootcmd 'fatload mmc 0:1 81000000 zImage; fatload mmc 0:1 82000000 dtb; bootz 81000000 - 82000000'
\end{verbatim}
}

{\footnotesize
The last thing to do is to define the kernel command line:
\begin{verbatim}
setenv bootargs console=ttyO0,115200n8 root=/dev/mmcblk0p2 rootwait ro
\end{verbatim}
}

\begin{itemize}
\item \code{rootwait} waits for the root device to be ready before
attempting to mount it. You may have a kernel panic otherwise.
\item \code{ro} mounts the root filesystem in read-only mode.
If this is possible, this is quite important to avoid random
filesystem checks at boot time, depending on how the system was shut
down, switched off or rebooted. Such filesystem checks can add a lot
of jitter from one boot to another, making boot time measurements
unpredicable and difficult to reproduce.
\end{itemize}

Last but not least, save your changes:
\begin{verbatim}
saveenv
\end{verbatim}

\section{Testing time!}

First, connect the USB webcam provided by your instructor, and point it
to an interesting direction ;)

Then, reset your board or power it on, and see it work as expected. If
you don't get what you expected, check your serial console for errors,
and if you're stuck, show your system to your instructor.