<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Operating Systems on Tech Philosopher</title><link>https://blog.bktus.com/en/tags/operating-systems/</link><description>Recent content in Operating Systems on Tech Philosopher</description><generator>Hugo</generator><language>en-US</language><lastBuildDate>Sat, 14 Jun 2025 01:09:13 +0200</lastBuildDate><atom:link href="https://blog.bktus.com/en/tags/operating-systems/index.xml" rel="self" type="application/rss+xml"/><item><title>Running a “Vanilla” Mainline Kernel on Raspberry Pi 5: Full Workflow of Trimming, Cross-Compilation, and Deployment</title><link>https://blog.bktus.com/en/archives/czh2is/</link><pubDate>Sat, 14 Jun 2025 01:09:13 +0200</pubDate><guid>https://blog.bktus.com/en/archives/czh2is/</guid><description>&lt;h2 id="summary">Summary&lt;/h2>
&lt;p>This post records how I turned the Raspberry Pi 5 into a minimal development and testing platform for the mainline Linux kernel (the vanilla kernel). It covers how I trimmed the repository down, a custom kernel config, cross-compilation and automated deployment scripts, a trick for removing overlays, and what I’ve learned from keeping it in sync with the mainline community over time. It should be useful for geeks who follow Linux mainline, ARM64 support, kernel development or upstream contributions, or who just like tinkering with the kernel.&lt;/p></description><content:encoded><![CDATA[<h2 id="summary">Summary</h2>
<p>This post records how I turned the Raspberry Pi 5 into a minimal development and testing platform for the mainline Linux kernel (the vanilla kernel). It covers how I trimmed the repository down, a custom kernel config, cross-compilation and automated deployment scripts, a trick for removing overlays, and what I’ve learned from keeping it in sync with the mainline community over time. It should be useful for geeks who follow Linux mainline, ARM64 support, kernel development or upstream contributions, or who just like tinkering with the kernel.</p>
<h2 id="background-and-motivation">Background and Motivation</h2>
<p>Recently I’ve been studying the theory and architecture of the Linux kernel in depth, and I’m getting ready to properly move into OS kernel work. So I bought a Raspberry Pi 5 as a development board to learn and practice kernel development. But as soon as I started, I found that the Pi 5 can’t run the mainline Linux kernel directly. It can only rely on the <a href="https://github.com/raspberrypi/linux">kernel repository maintained by the Raspberry Pi team</a>. At the time, the latest branch was rpi-6.14.y (now it’s rpi-6.16.y). The repository is maintained by “dynamically pulling upstream mainline code + rebase + lots of custom patches”, which means tens of thousands of lines of changes and a history that keeps getting rewritten.</p>
<p>These custom patches really are important for the official kernel to run stably on the Raspberry Pi with every feature working. But for a developer like me, who <strong>just wants to study mainline kernel features</strong> and cares about the kernel itself, these patches turn into a burden:</p>
<ul>
<li>Syncing with mainline is hard, and merges often run into conflicts.</li>
<li>The version history is rewritten often, so it’s hard to trace back and compare.</li>
<li>Testing new mainline features or giving feedback becomes less straightforward.</li>
</ul>
<p>I looked at x86 development boards and found that most of them can run the mainline kernel directly, but they’re expensive and nowhere near as cost-effective as the Raspberry Pi 5. So I started thinking about how to get the Pi 5 to run the mainline kernel smoothly too. That way I could try out and test the latest kernel features at any time, and it would be easier to report problems and contribute patches for the ARM64 platform. My goal was clear: with as few patches as possible, and staying as close to upstream as possible, make the Raspberry Pi 5 an ideal ARM64 platform for my own mainline kernel experiments and learning.</p>
<h2 id="repository-structure-and-scope-of-changes">Repository Structure and Scope of Changes</h2>
<p>My approach is really simple and goes straight to the point: keep only the drivers and patches that are truly needed, and follow mainline closely for everything else. I only patch the drivers/ directory and focus on core hardware support, mainly:</p>
<ul>
<li>
<p><strong>SD card driver</strong>: makes sure the Raspberry Pi boots normally and the kernel can load the root filesystem. The boot firmware does part of the initialization itself, but the mainline kernel still needs the driver to mount the root filesystem.</p>
</li>
<li>
<p><strong>Wired network card (Ethernet)</strong>: makes it easy to log in remotely over SSH, download new kernel images, and do remote development and debugging. It’s one of the most important I/O channels during kernel development.</p>
</li>
<li>
<p><strong>UART serial port</strong>: the output window for kernel debugging and early print. I can watch the kernel log directly and tell how booting and running are going.</p>
</li>
<li>
<p><strong>USB controller</strong>: for mounting external devices or occasionally moving data offline, which covers more test scenarios.</p>
</li>
<li>
<p><strong>Basic GPIO, power management</strong> and other parts closely tied to the RPi5 hardware.</p>
</li>
<li>
<p>Remove support for subsystems from the official kernel that aren’t needed for kernel development, such as <strong>Wi-Fi, Bluetooth, GPU (VideoCore), HDMI and audio/video acceleration</strong>. They don’t mean much for studying and testing the kernel itself.</p>
</li>
</ul>
<p><strong>Maintain the Raspberry Pi 5 DTS (Device Tree) configuration under arch/arm64/boot/dts/</strong></p>
<ul>
<li>The focus is to make sure the RPi5’s hardware resources, CPU configuration and peripheral mappings are recognized correctly at boot, so the mainline kernel runs smoothly.</li>
</ul>
<p><strong>Keep everything else 1:1 in sync with Linus’s mainline</strong></p>
<ul>
<li>Apart from the few patches above, the rest of the repository stays exactly the same as the <a href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git">official mainline repository</a>.</li>
<li>Regularly (say, every month or every two weeks) pull the latest code from mainline. Then I only need to apply a handful of patches and resolve a few small conflicts.</li>
</ul>
<p>With this approach, the repository stays minimal and easy to maintain, and it also lays the groundwork for slimming down the config and keeping up with mainline quickly later on.</p>
<h2 id="example-of-a-custom-kernel-config">Example of a Custom Kernel Config</h2>
<p>During the actual deployment, I prepared my own .config for the Raspberry Pi 5 mainline kernel. The goal was to cover my own development, testing and service needs while <strong>cutting out unrelated features as much as possible and keeping build size and build time to a minimum</strong>. Getting there took a lot of trial and error and tuning.</p>
<h3 id="phase-one-trim-everything-keep-only-the-core">Phase One: Trim Everything, Keep Only the Core</h3>
<p>The first version of the .config turned off almost every driver and feature module I didn’t think I needed, including:</p>
<ul>
<li><strong>All network card drivers except the onboard one</strong> (I only kept the driver for the Raspberry Pi 5’s onboard Cadence network card)</li>
<li><strong>Virtualization support</strong> (KVM and so on)</li>
<li><strong>The graphics subsystem, sound cards, HDMI, multimedia acceleration and so on</strong></li>
<li><strong>All network file systems</strong></li>
<li><strong>All file systems except ext4 and the SD card (mmcblk)</strong></li>
<li><strong>Some crypto algorithms and kernel mechanisms</strong> related to the modules above</li>
<li>I even <strong>turned off cgroup</strong></li>
</ul>
<p>After a few rounds of debugging and real testing, the final config may not be the “most minimal” one in theory. But it already cut the kernel build time a lot, and the kernel boots stably and handles the basic functions I need.</p>
<h3 id="phase-two-practical-extensions-for-docker-workloads-and-everyday-services">Phase Two: Practical Extensions for Docker Workloads and Everyday Services</h3>
<p>As my kernel experiments went further, I realized that:</p>
<ul>
<li>I needed Docker to run some real workloads and check the kernel’s stability and compatibility;</li>
<li>I needed to support everyday things like a LAN file server (NAS);</li>
<li>I also wanted another Raspberry Pi to run my self-built kernel long term, hosting services that aren’t so critical.</li>
</ul>
<p>So the newer config files gradually <strong>added back some features</strong>, such as:</p>
<ul>
<li><strong>cgroup, iptables, fuse, overlayfs, wireguard, macvlan, NFS, Samba</strong> and other common kernel modules (to support Docker and file services)</li>
<li>Most of the new features are built as modules and loaded on demand, which further improves boot and runtime efficiency</li>
</ul>
<p>This step made the build a little slower, but the config is still very lean compared with the mainline default, and it fits what I actually use and test much better.</p>
<p><strong>The config files are hosted at:</strong> <a href="https://git.bktus.com/Linux/kernel-configs/">https://git.bktus.com/Linux/kernel-configs/</a></p>
<p>Some key config files, in timeline order:</p>
<ul>
<li>eric-rpi-v1_defconfig</li>
<li>eric-vanilla-c-6.13_defconfig</li>
<li>eric-vanilla-c-6.14_defconfig</li>
<li>eric-vanilla-c-6.15_defconfig</li>
<li>eric-vanilla-v1_defconfig</li>
<li>eric-vanilla-v2_defconfig</li>
<li>eric-vanilla-v3_defconfig</li>
</ul>
<p>From these config files, you can see how I went from extreme trimming to gradually adding things back as I debugged and tuned.</p>
<h2 id="advantages-and-use-cases">Advantages and Use Cases</h2>
<h3 id="close-to-mainline-quick-to-try-and-test-new-features">Close to Mainline, Quick to Try and Test New Features</h3>
<p>The biggest benefit of keeping the patches minimal is that you can take the latest patches from the linux-next branch, or even new features from Linus’s merge window, and run them on the RPi5 at almost “zero cost”. Whether it’s a new scheduler, new file system features, improvements to the virtualization and security subsystems (like KVM, eBPF and LSM), or Zstd compression and new memory management mechanisms, as soon as something changes in mainline, you can <strong>test it on real hardware right away, check its compatibility and performance, and report problems and suggestions to the upstream ARM64 community in time</strong>.</p>
<p>More importantly, <strong>by running a “vanilla” kernel, you can see and understand how the mainline kernel itself is implemented, as faithfully as possible</strong>. You avoid the “side effects” introduced by the Raspberry Pi vendor patches, and you don’t have to worry about mistaking a problem in a vendor patch for a mainline bug.</p>
<p>I maintain the patches with merge rather than rebase, so the repository history is cleaner and the differences between mainline and my local changes are clear at a glance. Almost every mainline merge goes through “instantly”, so you can always keep up with the latest kernel development. For example, you can pull linux-next for testing at any time, or benchmark new kernel features, and it really feels like you’re taking part.</p>
<p>This approach is really valuable for kernel developers, upstream enthusiasts and even “hardcore” hackers. The bugs you run into and the patches you submit are real problems in a mainline environment, <strong>so you can take them straight to the kernel community.</strong></p>
<h3 id="more-efficient-maintenance-and-development">More Efficient Maintenance and Development</h3>
<ul>
<li><strong>Very few patches, very few conflicts</strong>: the repository only covers the hardware support the RPi5 really needs. For each upstream merge, you only have to watch drivers/net/arm/…, drivers/usb/…, drivers/bus/… and arch/arm64/boot/dts/broadcom/…, so conflicts are very limited and there’s little maintenance work.</li>
<li><strong>Debugging and rolling back are really easy</strong>: if mainline introduces a regression or something odd, you only need to check a handful of patches to roll back or adjust. There’s no need to look for a needle in a haystack across thousands of lines of vendor patches.</li>
<li><strong>Easier to contribute upstream</strong>: your driver patches and bug fixes are very “clean”. You can turn them straight into patches and send them to the kernel mailing list, where they’re easy for the community to review and won’t get stuck because of interference from vendor patches.</li>
</ul>
<h3 id="an-ideal-platform-for-development-testing-and-learning">An Ideal Platform for Development, Testing and Learning</h3>
<ul>
<li><strong>Exploring and testing new features</strong>: the RPi5 is a low-cost, mainstream ARM64 development board, so you can easily test linux-next or any mainline branch on it and give test results and feedback to the upstream community.</li>
<li><strong>Performance tuning and driver testing</strong>: you can run performance benchmarks, optimize drivers, do power experiments and so on, and see how new mainline features really perform on ARM64.</li>
<li><strong>A teaching and self-study environment</strong>: for people learning Linux drivers, device trees and HAL, a minimal environment cuts down “environmental noise” as much as possible, so they can focus on understanding the mainline driver framework and hardware abstraction.</li>
</ul>
<p>The official repository has a clear advantage in driver coverage and vendor support, and it suits users who want an “out-of-the-box, full multimedia experience”. My mainline repository focuses on “staying close to upstream, simple maintenance and easy development”. If you just want to watch videos, play games or run a GUI desktop on the Raspberry Pi 5, the official repository is probably more convenient. But for kernel engineers, developers and people who love to experiment, a “lightweight mainline repository” lets you focus more on the kernel itself.</p>
<h2 id="how-to-use-and-contribute">How to Use and Contribute</h2>
<p>In theory, the Raspberry Pi 5 is a lot faster than the Raspberry Pi 4, and it can compile its own kernel just fine. The experience isn’t bad either (with more than 4GB of RAM). But if you need to do kernel or kernel module development and turn on things like code indexing, it doesn’t have enough power.</p>
<p>I also tried adding the official SSD Kit (512GB). That solved the I/O throughput problem, but in the end I still hit a CPU bottleneck, because it only has 4 cores. So if you just need a working, up-to-date kernel and don’t compile often, you can build and install it on the Raspberry Pi itself. But if you need to go further with development and debugging, I still strongly recommend cross-compilation. That means compiling the kernel and kernel modules on a PC or workstation (usually x86), and then copying them to the Raspberry Pi over the network (or with the SD card). For example, my workstation has 12 cores, and builds take several times less time on it (compared with the RPi5’s 4 cores). So below, I’ll use my own cross-compilation setup as the example.</p>
<p>Before that, you need to install an ARM64 cross-compilation environment. I suggest installing ccache to cut the time of repeated builds even more. If you don’t want to use ccache, remove the ccache part from all the commands in the following sections.</p>
<pre tabindex="0"><code>sudo apt install bc bison flex libssl-dev make libc6-dev libncurses5-dev
sudo apt install crossbuild-essential-arm64
sudo apt install ccache
</code></pre><h3 id="clone-the-repositories-and-check-out-the-latest-branch">Clone the Repositories and Check Out the Latest Branch</h3>
<p>My repository is on my own private Git server, but you can use my mirror on GitHub. I regularly track Linus’s mainline repository and update the main branch.</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>git clone https://git.bktus.com/Linux/kernel-configs.git
</span></span><span style="display:flex;"><span>git clone https://github.com/saturneric/linux <span style="color:#f92672">(</span>recommand<span style="color:#f92672">)</span> or https://git.bktus.com/linux/kernel.git
</span></span><span style="display:flex;"><span>cd linux
</span></span><span style="display:flex;"><span>git checkout main
</span></span></code></pre></div><p>Note: the first command clones the <a href="https://git.bktus.com/Linux/kernel-configs/">kernel config repository</a> I mentioned earlier. So <strong>don’t use the config files provided by the Raspberry Pi team in the later steps</strong> (they turn on lots of features), because that will most likely give you a compiled kernel that doesn’t boot.</p>
<p>Of the two, <a href="https://github.com/saturneric/linux">https://github.com/saturneric/linux</a> is on GitHub and should be the fastest in theory, so if you don’t have any special needs, try to clone from there. <a href="https://git.bktus.com/linux/kernel.git">https://git.bktus.com/linux/kernel.git</a> is the repository hosted on my own server, and the GitHub repository above is a mirror of it.</p>
<h3 id="basic-configuration">Basic Configuration</h3>
<p>You need to pick a config file from the kernel-configs repository that fits the current version, rename it to <code>.config</code> and copy it into the root of the kernel repository.</p>
<pre tabindex="0"><code>cp ../kernel-configs/eric-vanilla-c-6.16_defconfig .config
</code></pre><p>You can trim the kernel further on top of my config, or add features.</p>
<pre tabindex="0"><code>make ARCH=arm64 CROSS_COMPILE=&#34;ccache aarch64-linux-gnu-&#34; menuconfig
</code></pre><h3 id="build">Build</h3>
<p>Once the cross-compilation environment is ready, you can build right away. How long it takes depends on your config and your machine. For me, it takes about 10 minutes.</p>
<pre tabindex="0"><code>make ARCH=arm64 CROSS_COMPILE=&#34;ccache aarch64-linux-gnu-&#34; -j$(nproc)
</code></pre><h3 id="copy-the-kernel-and-kernel-modules-to-the-raspberry-pi">Copy the Kernel and Kernel Modules to the Raspberry Pi</h3>
<p>You can use the script I provide to quickly transfer the kernel image and kernel modules you just built to the home directory of the default user on the Raspberry Pi. I strongly recommend not giving the kernel image and device tree the same names as the Raspberry Pi 5’s default kernel. Use names like <code>kernel-vanilla.c.img</code> and <code>bcm2712d0-rpi-5-b.vanilla.c.dtb</code> instead, so even if something goes wrong, we can quickly switch back to the original working kernel or device tree through the config file. Also, the rsync in the script needs passwordless SSH, so I suggest setting up your public key beforehand.</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span><span style="color:#75715e">#!/bin/bash
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ====== Configurable parameters (change them to fit your setup) ======</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Local directory for the kernel build artifacts</span>
</span></span><span style="display:flex;"><span>LOCAL_KERNEL_ARTIFACTS<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;./kernel-artifacts&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># SSH connection info for the target Raspberry Pi (e.g. pi@192.168.1.100)</span>
</span></span><span style="display:flex;"><span>REMOTE_HOST<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;pi@192.168.1.100&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Target directory on the Raspberry Pi (an absolute path is recommended, e.g. /home/pi/kernel)</span>
</span></span><span style="display:flex;"><span>REMOTE_KERNEL_ARTIFACTS<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/home/pi/kernel&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Target kernel file name (customizable, default kernel_2712.img)</span>
</span></span><span style="display:flex;"><span>KERNEL_IMG<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;kernel-vanilla.c.img&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Device tree file name (customizable)</span>
</span></span><span style="display:flex;"><span>DTB_FILE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;bcm2712d0-rpi-5-b.vanilla.c.dtb&#34;</span>
</span></span><span style="display:flex;"><span>DTB_SOURCE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;arch/arm64/boot/dts/broadcom/bcm2712d0-rpi-5-b.dtb&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>set -e
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Cleaning and preparing the local directory &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>rm -rf <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>mkdir -p <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Installing kernel modules into the local output directory &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>make ARCH<span style="color:#f92672">=</span>arm64 CROSS_COMPILE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;aarch64-linux-gnu-&#34;</span> INSTALL_MOD_PATH<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span> modules_install
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Copying the kernel image and device tree &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>cp -v -f arch/arm64/boot/Image.gz         <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>cp -v -f <span style="color:#e6db74">&#34;</span>$DTB_SOURCE<span style="color:#e6db74">&#34;</span>                    <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Uploading the kernel artifacts to the Raspberry Pi &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>ssh <span style="color:#e6db74">&#34;</span>$REMOTE_HOST<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;sudo mkdir -p </span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>rsync -avz --progress --delete <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">/&#34;</span> <span style="color:#e6db74">&#34;</span>$REMOTE_HOST<span style="color:#e6db74">:</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Upload complete. You can now log in to the Raspberry Pi and configure/switch the boot kernel &lt;&lt;&lt;&#34;</span>
</span></span></code></pre></div><p>So after the script finishes, all the files you’re about to install are already on the Raspberry Pi. But note that they’ve only been copied over. The new kernel isn’t actually in use yet.</p>
<h3 id="install-the-kernel-and-kernel-modules-on-the-raspberry-pi">Install the Kernel and Kernel Modules on the Raspberry Pi</h3>
<p>With the script below, you can easily install the files you just copied to the Raspberry Pi (device tree, kernel and kernel modules) to where they should go. <strong>Note: this script touches several critical system directories, so double-check the parameters to avoid deleting or overwriting important files by mistake.</strong></p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span><span style="color:#75715e">#!/bin/bash
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># RPi5 mainline kernel local deployment/flashing script</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Installs the kernel image, device tree and kernel modules into /boot and /lib/modules</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Make sure you run it on the Raspberry Pi with sudo privileges</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>set -e
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ====== Configurable parameters (change them to fit your setup) ======</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Directory holding the uploaded artifacts (the ones just synced over with rsync)</span>
</span></span><span style="display:flex;"><span>REMOTE_KERNEL_ARTIFACTS<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/home/pi/kernel&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Kernel image name (keep it the same as in the upload script)</span>
</span></span><span style="display:flex;"><span>KERNEL_IMG<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;kernel-vanilla.c.img&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Device tree file name</span>
</span></span><span style="display:flex;"><span>DTB_FILE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;bcm2712d0-rpi-5-b.vanilla.c.dtb&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Location of the kernel image and device tree</span>
</span></span><span style="display:flex;"><span>BOOT_FIRMWARE_PATH<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/boot/firmware&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Actual install directory for kernel modules (target)</span>
</span></span><span style="display:flex;"><span>LIB_MODULES_PATH<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/lib/modules&#34;</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 1. Installing the kernel image and device tree &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>sudo cp -v <span style="color:#e6db74">&#34;</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>sudo cp -v <span style="color:#e6db74">&#34;</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 2. Setting permissions for the image and DTB &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>sudo chown root:root <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>sudo chmod <span style="color:#ae81ff">644</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 3. Installing kernel modules &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Modules with the same version number are overwritten automatically</span>
</span></span><span style="display:flex;"><span>sudo rsync -av --progress <span style="color:#e6db74">&#34;</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">/lib/modules/&#34;</span> <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 4. Setting permissions for kernel modules &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>sudo chown -R root:root <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span>
</span></span><span style="display:flex;"><span>find <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span> -type d -exec sudo chmod <span style="color:#ae81ff">755</span> <span style="color:#f92672">{}</span> <span style="color:#ae81ff">\;</span>
</span></span><span style="display:flex;"><span>find <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span> -type f -exec sudo chmod <span style="color:#ae81ff">644</span> <span style="color:#f92672">{}</span> <span style="color:#ae81ff">\;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Kernel and modules deployed. If needed, update /boot/config.txt to point to the new kernel &lt;&lt;&lt;&#34;</span>
</span></span></code></pre></div><h3 id="configure-the-raspberry-pi-firmware-to-boot-the-new-kernel">Configure the Raspberry Pi Firmware to Boot the New Kernel</h3>
<p>You need to edit <code>/boot/firmware/config.txt</code> so that the Raspberry Pi firmware boots the new kernel and passes it the matching device tree to use. Mainly, you change or add the two lines below.</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ini" data-lang="ini"><span style="display:flex;"><span><span style="color:#75715e"># DTB</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">device_tree</span><span style="color:#f92672">=</span><span style="color:#e6db74">bcm2712d0-rpi-5-b.vanilla.c.dtb</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Kernel</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">kernel</span><span style="color:#f92672">=</span><span style="color:#e6db74">kernel-vanilla.c.img</span>
</span></span></code></pre></div><h2 id="removing-the-raspberry-pis-dts-overlay-feature-and-avoiding-common-boot-problems">Removing the Raspberry Pi’s DTS Overlay Feature (and Avoiding Common Boot Problems)</h2>
<p>The Raspberry Pi team added a DTS overlay mechanism to their platform. When the main device tree is loaded, this design lets extra overlay fragments be stacked on top of it dynamically, depending on what the firmware or the user needs. That way, peripherals, parameters or features can be turned on or adjusted flexibly. For example, if you add a new module or feature to your Raspberry Pi, you only need to configure an overlay to activate it, which is pretty convenient.</p>
<p>But this mechanism is currently <strong>not supported by the mainline Linux kernel</strong>.</p>
<p>If overlay settings are enabled in <code>/boot/firmware/config.txt</code> and the overlay files don’t match the device tree (DTB) version of the mainline kernel, it’s very easy to end up with boot failures, devices that aren’t recognized and similar problems. For kernel developers who want a minimal, pure mainline kernel experience, this often causes more trouble than it saves.</p>
<h3 id="my-approach">My Approach</h3>
<p>For me personally, DTS overlays are very flexible, but the mainline kernel doesn’t support them natively, and they get in the way of kernel debugging and a clean environment. So I chose to <strong>remove the overlay feature completely</strong> and keep only the main device tree file. The direct side effect is that <strong>some hardware parameters (like CPU boot parameters) are normally injected through overlays, so just removing overlays will stop the Raspberry Pi from booting.</strong></p>
<p><strong>The fix</strong>: I got around this by writing the required CPU parameters directly into the main device tree file. Actually, the official device tree file bcm2712d0-rpi-5-b.dtb is made for the no-overlay case. As long as you use it as the main device tree, the system boots normally without any overlay.</p>
<h3 id="how-to-remove-the-overlay-config-step-by-step">How to Remove the Overlay Config (Step by Step)</h3>
<p>Edit /boot/firmware/config.txt, make sure only device_tree is set, and remove or comment out all overlay settings (such as the dtoverlay= lines). Here’s an example:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ini" data-lang="ini"><span style="display:flex;"><span><span style="color:#75715e"># Specify the main device tree file (bcm2712d0-rpi-5-b.vanilla.c.dtb is recommended)</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">device_tree</span><span style="color:#f92672">=</span><span style="color:#e6db74">bcm2712d0-rpi-5-b.vanilla.c.dtb</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Don&#39;t load any overlay</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e">#dtoverlay=xxx      # Comment out or delete all of these</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># It&#39;s best to also turn off the other overlay auto-detection features</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">camera_auto_detect</span><span style="color:#f92672">=</span><span style="color:#e6db74">0</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">display_auto_detect</span><span style="color:#f92672">=</span><span style="color:#e6db74">0</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Kernel image to boot</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">kernel</span><span style="color:#f92672">=</span><span style="color:#e6db74">kernel-vanilla.c.img</span>
</span></span></code></pre></div><h3 id="check-other-overlay-related-settings">Check Other Overlay-Related Settings</h3>
<ul>
<li>I recommend turning off camera_auto_detect and display_auto_detect.</li>
<li>Make sure no dtoverlay= entry is enabled.</li>
</ul>
<h3 id="reboot-the-raspberry-pi">Reboot the Raspberry Pi</h3>
<p>Once the changes above are in place, reboot the device. The system will load the main device tree file directly and <strong>won’t apply any overlay anymore</strong>, which keeps the mainline kernel as clean and controllable as possible. If everything works fine afterward, you can remove the <code>/boot/firmware/overlays</code> directory to save space. This also makes sure these overlays can never be loaded at boot again, no matter what, so they can’t pollute the environment.</p>
<h3 id="recommended-minimal-configtxt-template">Recommended Minimal config.txt Template</h3>
<pre tabindex="0"><code># Only specify the main device tree and the mainline kernel image
device_tree=bcm2712d0-rpi-5-b.vanilla.c.dtb
kernel=kernel-vanilla.c.img

# Turn off overlay auto-detection
camera_auto_detect=0
display_auto_detect=0

# Other common parameters can stay
disable_fw_kms_setup=1
arm_64bit=1
disable_overscan=1
arm_boost=1
</code></pre><h2 id="submitting-patches-or-issues">Submitting Patches or Issues</h2>
<ul>
<li>If you run into any problems while following this post, or find a step that keeps the process from working, feel free to let me know anytime.</li>
<li>If you fix a compatibility problem or find a bug while using it, you’re also welcome to open an issue directly, so we can discuss it with other users and improve the project together.</li>
<li>If you add hardware support, make performance improvements or port new mainline patches on top of this repository, I suggest generating standard patches with scripts/format-patch.sh and then sending them straight to the upstream Linux kernel mailing list, so the community can take in the improvements.</li>
</ul>
<p>GitHub repository: <a href="https://github.com/saturneric/linux">https://github.com/saturneric/linux</a></p>
<h2 id="long-term-maintenance-notes">Long-Term Maintenance Notes</h2>
<p>Neither this repository nor this post is a one-off “pop-up project”. Since I’ll be studying the Linux kernel and operating system theory for a long time, I’ll keep following every major mainline kernel release (including the rc1 … rcX stages) and merge the key changes and adaptations into the main branch in time. Before each mainline sync, I first build it on my workstation (Debian Testing) and then test it on a real Raspberry Pi 5, to make sure the repository always works and the process runs smoothly.</p>
<p>If you’re also doing mainline kernel development on a Raspberry Pi, or you run into compatibility or adaptation problems, feel free to leave a comment. I also hope you’ll join the mainline kernel community and help the ARM64 platform keep getting better.</p>
]]></content:encoded></item></channel></rss>