Skip Navigation

Assignment 6: Configure 3D Graphics and CCU Kernel

For this assignment, you will switch your Raspberry Pi to use the newer, better supported 3D graphics driver. You will also enable the CCU “tealrepo” software repository, from which you will install the rpi5-teal kernel.

Page Contents

Background

A fresh installation of Alpine Linux on the Raspberry Pi 5 isn’t quite ready to run all the software we’d like to be able to use on it. For starters, the default configuration uses a largely abandoned legacy video driver for its onboard VideoCore graphics. There is a newer driver with accelerated 3D support in the kernel, but a device tree overlay must be enabled in the firmware configuration to allow that driver to load and work properly. In addition, Alpine Linux needs an extra package to provide the 3D graphics support.

Alpine Linux’s default kernels across both the AARCH64 and x86_64 architectures leave a bit to be desired. At the time when a Linux kernel is compiled, the kernel configuration can be adjusted to enable or disable certain features and drivers. Many drivers for USB devices are not included in the basic Alpine Linux kernels, as support for them has simply not been turned on at compilation time. Thus, a number of USB devices that would ordinarily “just work” on a typical Linux system, including things like drawing tablets, radio tuners, and TV adapters, won’t be usable under the default kernel supplied by Alpine Linux.

To rectify this problem, I have created a custom build of the Linux kernel and made it available via a CCU-hosted software repository. This build has support for just about every imaginable USB device enabled, making it easier to use the Pi with various external devices. The procedure for this assignment will culminate in running this custom kernel build.

Procedure

This assignment is set up as a tutorial. Follow the steps in order.

Step 1: Enable VC4 3D Graphics

In order to configure the system to use the newer, better supported 3D graphics driver, we need to edit the firmware configuration file. In Raspberry Pi OS, this file used to be at /boot/firmware/config.txt. However, Alpine Linux does things a little differently. Instead of editing config.txt directly, that file is generated by the installation of the kernel package. It is configured to include a file named “usercfg.txt” that contains our customizations. On Alpine Linux, these files are located in /boot instead of /boot/firmware.

Create the /boot/usercfg.txt file by running:

vi /boot/usercfg.txt

While we’re here, we might as well enable HDMI audio so that you can hear sounds if your screen or TV has working speakers. Add the following device tree parameter:

dtparam=audio=on

We might as well also go ahead and get the RTC battery charging:

dtparam=rtc_bbat_vchg=3000000

To switch to the VC4 3D KMS driver, we need to add a device tree overlay, which will replace the legacy graphics device components with the newer ones. Add the following 3 lines to usercfg.txt:

dtoverlay=vc4-kms-v3d
max_framebuffers=2
disable_fw_kms_setup=1

The first line enables the device tree overlay for the new video driver, while the second limits the number of video outputs to 2. Since the Raspberry Pi 5 only has 2 HDMI ports, this limit makes sense. Finally, we tell the firmware not to set up the display at boot time. We’ll let our Linux kernel do that instead.

In order to make use of the new 3D driver, we need to add a package to our Alpine Linux installation. Run the following commands:

apk update
apk add mesa-dri-gallium

Once the mesa-dri-gallium package has been successfully added, you can then:

reboot

After rebooting, verify that the 3D driver has been loaded:

ls /dev/dri/card0

If the new driver has been enabled successfully, then the above command will produce some output. Something went wrong if you get a “no such file or directory” error. Double-check that you got the dtoverlay line for the graphics driver right in usercfg.txt, including the “v” before the “3d” at the end.

You can also check that the RTC battery is charging by running:

cat /sys/class/rtc/rtc0/charging_voltage

If you compare this command to the one in the Charge the RTC Battery and Connect to WiFi assignment from Raspberry Pi OS, you’ll notice that this command is a lot shorter. Thanks to symbolic links, the charging_voltage file is made available via a few different paths in sysfs. This is exactly the same file as /sys/devices/platform/soc/soc:rpi_rtc/rtc/rtc0/charging_voltage, but we can get to it using a shorter path.

Step 2: Display Startup Messages

Notice that the Pi goes directly to a login prompt after booting, and we can’t see the startup messages. This situation is caused by the fact that our initial ramdisk, which is used by Alpine Linux to load kernel drivers before we have the root filesystem mounted, doesn’t have the graphics drivers included. To fix this issue, we need to add the “kms” feature to our initfs. Edit the file /etc/mkinitfs/mkinitfs.conf using vi. Add kms to the end of the features list like so. Check to see if the “mmc” feature is listed twice. If it is, delete the second one. Your features list should look like this:

features="base mmc usb ext4 kms"

Now we need to rebuild the initial ramdisk. Save the mkinitfs.conf file, exit vi, and run the following command:

mkinitfs

We also need to tell the kernel to initialize the first console (called tty1), so that the messages get printed correctly. To do this, we need to edit the firmware bootloader configuration file for the kernel command line. This file is located at /boot/cmdline.txt and can be edited with vi. It contains a pretty long line that should end with “rootfstype=ext4”. Add “console=tty1” to the end of the line, after leaving a space (omit the quotes). The end of the line should look like this (with the 3 dots representing the part of the line before the rootfs type, which you shouldn’t change):

... rootfstype=ext4 console=tty1

Save the file and exit vi, then test your changes by running:

reboot

You should see the service startup messages as the Pi boots.

Step 3: Add the CCU Software Repository

Over time, some of the packages that we build from source at CCU will make their way into our “tealrepo” software repository. This Internet-accessible resource will provide a way to distribute software applications that might not be in the official Alpine Linux repositories.

Every software repository in Alpine Linux is signed with an RSA key that allows the package manager to verify that the package is authentic. This signing process is designed to stop a man-in-the-middle attack, where the adversary could try to intercept network traffic between the user and CCU’s server, causing the user to download a malicious package instead of a genuine one.

In order to use the CCU tealrepo repository, we must first add the public key to the trusted keys that Alpine Linux can use. To accomplish this step, run:

cd /etc/apk/keys
wget https://mirror.coastal.edu/tealrepo/teal-repo@coastal.edu-66dcca7c.rsa.pub
cd

Once the key is added to the keys directory, edit /etc/apk/repositories and add the repository mirror line for tealrepo. Go ahead and change the URLs for the main, community, and testing repositories from http to https. Your repositories file should look like this:

https://dl-cdn.alpinelinux.org/alpine/v3.20/main
https://dl-cdn.alpinelinux.org/alpine/v3.20/community
https://mirror.coastal.edu/tealrepo/packages/v3.20
@testing https://mirror.coastal.edu/tealrepo/packages/v3.20

Update the repository metadata using:

apk update

You should see where the metadata have been downloaded for all 4 repositories. The last line of the output should start with “OK:” and provide the total number of packages available across all repositories.

Step 4: Switch to the rpi5-teal Kernel

Out of the box, Alpine Linux on the Raspberry Pi is using the “rpi” kernel. This kernel is a long-term support (LTS) kernel that has patches specific to the Raspberry Pi applied to it.

Take a look at /boot/config.txt by running:

cat /boot/config.txt

This file contains 4 effective lines (ones that are not comments or blanks). The line that begins with kernel= specifies the name of the kernel to boot, and it has a corresponding initial ramdisk (initfs) file on the initramfs line. 64-bit CPU features are enabled by another line, and then the usercfg.txt file is included from the last line.

A number of files, including various device tree binary (.dtb) files in the /boot directory, will be overwritten by a new kernel package. For this reason, we must do a slightly risky change of kernel, in which we uninstall the Alpine-provided rpi kernel and install the CCU-provided rpi5-teal kernel. To accomplish this switch, run the following commands, and be sure they complete successfully! Without an installed kernel, your Pi will NOT boot!

apk del linux-rpi
apk add linux-rpi5-teal

Look at /boot/config.txt again:

cat /boot/config.txt

Verify that the kernel and initramfs files now end in -teal. There is currently an oddity in the build script that leaves out the “rpi5” part, but this works for now. I have to fix the build script (or change the name to eliminate the extra dash) at some point in the future.

Now, assuming that everything is OK, switch to the new kernel:

reboot

After logging back into Alpine, run:

uname -r

Verify the kernel version ends in -rpi5-teal, indicating that you’re using the CCU kernel.

Submission Checklist

While logged into your Pi as the root user, run:

date
hostname
ls /dev/dri/card0
uname -r
cat /sys/class/rtc/rtc0/charging_voltage

How to Check Your Work

To verify that you have everything working properly, look at the output of the above commands:

  1. Be sure that your CCU username is part of your hostname.
  2. Be sure that the date shows a time during the period for this assignment this semester.
  3. The ls /dev/dri/card0 command should produce output that reads /dev/dri/card0 (likely in magenta color). If this command produces no output, then you’re still using the old video driver (check your /boot/usercfg.txt settings).
  4. The uname -r output should show -rpi5-teal in the name. If it only shows -rpi, then you either haven’t switched to the CCU kernel or you forgot to reboot after swapping the kernels.
  5. The RTC charging voltage should be 3000000.

Final Steps

Take a photo of your screen, and upload your photo to Moodle as the submission for this assignment.

Remember to power off Alpine Linux correctly when you’re finished:

poweroff

ABET Assessment

Successful completion of this assignment satisfies the following performance indicator: