Update 2017 Feb 25: I have updated the step-by-step instructions based on the suggested fixes and improvements contained in the reader comments. I also have copied the step-by-step instructions from this blog post to the README.md file hosted on https://github.com/michaelfranzl/rpi23-gen-image. From now on I will update the instructions only on github, so expect that the instructions in this blog post will grow slightly out of date.

This has been a long way coming. In February 2014, Broadcom announced that they would release the formerly closed-source drivers for the VideoCore IV (VC4) GPU of their BCM283x family of System-on-a-chip (SoC), powering Raspberry Pi’s.

To make a long story short, Eric Anholt started porting the Open Source drivers, as documented by this presentation early 2015, and contributed code to the Linux (Mainline) Kernel, libdrm, Mesa, and X.org. I’m sure it was a long and painful work. But the results are worth it. A picture says more than 1000 words:

Debian 9 (“Stretch”) running on my Raspberry Pi 2 (and 3), powered by Linux 4.9.0-rc3 Mainline/Vanilla Kernel. Notable in this image: Graphics driver is recognized as “Gallium” running on the VC4 GPU of the Broadcom 2836 system-on-a-chip (SOC). The glxgears benchmark runs with 60 FPS (the vsync of the monitor) and consumes very little CPU. Even the Raspberry I2C interface is recognized by the Linux Mainline Kernel.

To emphasize the point: It is no longer necessary to run specialized distributions (like Raspbian) or Linux kernels (like the Raspbian flavor) in order to have the Raspberry Pi well supported. And this is good news. Debian is a well established and maintained standard Distribution. And even though the Raspberry Pi is not powerful enough for the professional desktop user, it is powerful enough for the casual desktop user, and it is very small and cheap, which opens up a whole lot of possibities for new real-world applications.

I ran an additional test: Gnome even runs on Wayland (modern replacement for the X Window System) on the Raspberry Pi 2 (and 3):

Gnome on Wayland on Raspberry Pi 2

Remarks

It still is not a matter of a one-click installer to reproduce these results, you need some experience when you run into barriers. But it has gotten a whole lot easier. Github user drtyhlpr thankfully published the script rpi23-gen-image that can create a standard Debian distribution for the Raspberry Pi that can simply be copied to a SD card.

I have created a fork of this script to use the official Linux kernel instead of the Raspberry flavor one. Above screenshots are taken from a system that I’ve created with this script. My fork is developed into a slightly different direction:

Only official Debian releases 9 (“Stretch”) and newer are supported.

Only the official/mainline/vanilla Linux kernel is supported (not the raspberry flavor kernel).

The Linux kernel must be pre-cross-compiled on the PC running this script (instructions below).

Only U-Boot booting is supported.

The U-Boot sources must be pre-downloaded and pre-cross-compiled on the PC running this script (instructions below).

An apt caching proxy server must be installed to save bandwidth (instructions below).

The installation of the system to an SD card is done by simple copying or rsyncing, rather than creating, shrinking and expanding file system images.

The FBTURBO option is removed in favor or the working VC4 OpenGL drivers of the mainline Linux kernel.

All of these simplifications are aimed at higher bootstrapping speed and maintainability of the script. For example, we want to avoid testing of all of the following combinations:

RPi2 with u-boot, with official kernel
RPi2 without u-boot, with official kernel
RPi2 with u-boot, with raspberry kernel
RPi2 without u-boot, with raspberry kernel
RPi3 with u-boot, with official kernel
RPi3 without u-boot, with official kernel
RPi3 with u-boot, with raspberry kernel
RPi3 without u-boot, with raspberry kernel

Thus, the script only supports:

RPi2 with u-boot with official kernel
RPi3 with u-boot with official kernel

A RPi2 (setting RPI_MODEL=2) is well supported. It will run the arm architecture of Debian, and a 32-bit kernel. You should get very good results, see my related blog posts:

The newer RPi3 (setting RPI_MODEL=3) is supported too. It will run the arm64 architecture of Debian, and a 64-bit kernel. The support of this board by the Linux kernel will very likely improve over time.

In general, this script is EXPERIMENTAL. I do not provide ISO file system images. It is better to master the process rather than to rely on precompiled images. In this sense, use this project only for educational purposes.

How to do it

Basically, we will deboostrap a minimal Debian 9 (“Stretch”) system for the Raspberry on a regular PC running also Debian 9 (“Stretch”). Then we copy that system onto a SD card, then boot it on the Raspberry.

We will work with the following directories:

1

2

3

4

5

~/workspace

|- rpi23-gen-image

|- linux

|- u-boot

|- raspberry-firmware

Set up your working directory:

1

2

mkdir workspace

cd workspace

Do the following steps as root user.

Set up caching for apt

This way, you won’t have to re-download hundreds of megabytes of Debian packages from the Debian server every time you run the rpi23-gen-image script.

1

apt-get install apt-cacher-ng

Check its status page:

1

http://localhost:3142

Install dependencies

The following list of Debian packages must be installed on the build system because they are essentially required for the bootstrapping process.

Kernel compilation

Get the latest Linux mainline kernel. This is a very large download, about 2GB. (For a smaller download of about 90 MB, consider downloading the latest stable kernel as .tar.xz from https://kernel.org.)

Working configuration files for this Linux kernel revision are included in this repository. (working-rpi2-linux-config.txt and working-rpi3-linux-config.txt).

If you want to generate the default .config file that is also working on the Raspberry, execute

1

make mrproper

For a RPi2:

1

make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-multi_v7_defconfig

For a RPi3:

1

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-defconfig

Whichever .config file you have at this point, if you want to get more control as to what is enabled in the kernel, you can run the graphical configuration tool at this point:

1

apt-get install libglib2.0-dev libgtk2.0-dev libglade2-dev

For a RPi2:

1

make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-gconfig

For a RPi3:

1

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-gconfig

Before compiling the kernel, back up your .config file so that you don’t lose it after the next make mrproper:

1

cp.config../kernelconfig-backup.txt

Compiling the kernel

Clean the sources:

1

make mrproper

Optionally, copy your previously backed up .config:

1

cp../kernelconfig-backup.txt.config

Find out how many CPU cores you have to speed up compilation:

1

NUM_CPU_CORES=$(grep-cprocessor/proc/cpuinfo)

Run the compilation on all CPU cores. This takes about 10 minutes on a modern PC:

For a RPi2:

1

make-j${NUM_CPU_CORES}ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-

For a RPi3:

1

make-j${NUM_CPU_CORES}ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

Verify that you have the required kernel image.

For a RPi2 this is:

1

./arch/arm/boot/zImage

For a RPi3 this is:

1

./arch/arm64/boot/Image.gz

U-Boot bootloader compilation

1

2

cd..

git clonegit://git.denx.de/u-boot.git

Confirmed working revision: b24cf8540a85a9bf97975aadd6a7542f166c78a3

Shell

1

git checkoutb24cf8540a

Let’s increase the maximum kernel image size from the default (8 MB) to 64 MB. This way, u-boot will be able to boot even larger kernels. Edit
./u-boot/include/configs/rpi.h and add above the very last line (directly above “#endif”):

C

1

#define CONFIG_SYS_BOOTM_LEN (64 * 1024 * 1024)

Find out how many CPU cores you have to speed up compilation:

1

NUM_CPU_CORES=$(grep-cprocessor/proc/cpuinfo)

Compile for a RPi model 2 (32 bits):

1

make-j${NUM_CPU_CORES}ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-rpi_2_defconfig all

Compile for a RPi model 3 (64 bits):

1

make-j${NUM_CPU_CORES}ARCH=arm CROSS_COMPILE=aarch64-linux-gnu-rpi_3_defconfig all

Verify that you have the required bootloader file:

1

./u-boot.bin

Pre-download Raspberry firmware

The Raspberry Pi still needs some binary proprietary blobs for booting. Get them:

You may want to modify the variables according to the section “Command-line parameters” below.

The file example.sh in my github repostory contains a working example.

Install the system on a SD card

Insert a SD card into the card reader of your host PC. You’ll need two partitions on it. I’ll leave as an exercise for the reader the creation of a partition table according to the following output of fdisk for a 64GB card:

1

2

3

Device Boot Start End Sectors Size Id Type

/dev/mmcblk0p1 2048 500000 497953 243.1M c W95 FAT32 (LBA)

/dev/mmcblk0p2 501760 62552063 62050304 29.6G 83 Linux

The following commands will erase all contents of the SD card and install the system (copy via rsync) on the SD card:

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

umount/dev/mmcblk0p1

umount/dev/mmcblk0p2

mkfs.vfat/dev/mmcblk0p1

mkfs.ext4/dev/mmcblk0p2

mkdir-p/mnt/raspcard

mount/dev/mmcblk0p2/mnt/raspcard

mkdir-p/mnt/raspcard/boot/firmware

mount/dev/mmcblk0p1/mnt/raspcard/boot/firmware

rsync-a./images/stretch/build/chroot//mnt/raspcard

umount/dev/mmcblk0p1

umount/dev/mmcblk0p2

Note about SD cards: Cheap (or sometimes even professional) SD cards can be weird at times. I’ve repeatedly noticed corrupt/truncated files even after proper rsync and proper umount on different brand new SD cards. TODO: Add a method to verify all file checksums after rsync.

Try booting the Raspberry

Insert the SD card into the Raspberry Pi, and if everything went well, you should see a console-based login prompt on the screen. Login with the login details you’ve passed into the script (USER_NAME and PASSWORD).

Alternatively, if you have included “avahi-daemon” in your APT_INCLUDES, you don’t need a screen and keyboard and can simply log in via SSH from another computer, even without knowing the Rasberry’s dynamic/DHCP IP address (replace “hostname” and “username” with what you have set as USER_NAME and HOSTNAME above):

1

ssh username@hostname.local

Finishing touches directly on the Raspberry

Remember to change usernames, passwords, and SSH keys!

Check uber-low RAM usage

Running top shows that the freshly booted system uses only 23 MB out of the availabl 1GB RAM! Confirmed for both RPi2 and RPi3.

Network Time Synchronization

The Raspberry doesn’t have a real time clock. But the default systemd conveniently syncs time from the network. Check the output of timedatectl. Confirmed working for both RPi2 and RPi3.

Hardware Random Number Generator

The working device node is available at /dev/hwrng. Confirmed working for both RPi2 and RPi3.

I2C Bus

Also try I2C support:

1

2

apt-get install ic2-tools

i2cdetect-y0

Confirmed working for both RPi2 and RPi3.

Test onboard LEDs

As of the kernel revision referenced above, this only works on the RPi2. The RPi3 has only the red PWR LED on all the time, but otherwise is working fine.

By default, the green onboard LED of the RPi blinks in a heartbeat pattern according to the system load (this is done by kernel feature LEDS_TRIGGER_HEARTBEAT).

To use the green ACT LED as an indicator for disc access, execute:

1

echo mmc0>/sys/class/leds/ACT/trigger

To toggle the red PWR LED:

1

2

echo0>/sys/class/leds/PWR/brightness# Turn off

echo1>/sys/class/leds/PWR/brightness# Turn on

Or use the red PWR LED as heartbeat indicator (kernel option for this must be enabled):

Kernel compilation directly on the Rasberry

Only successfully tested on the RPi2. Not yet tested on the RPI3.

In case you want to compile and deploy another Mainline Linux kernel directly on the Raspberry, proceed as described above, but you don’t need the ARCH and CROSS_COMPILE flags. Instead, you need the -fno-pic compiler flag for modules. The following is just the compilation step (configuration and installation omitted):

“Rapsberry Pi” in Wikipedia says: “The new BCM2837 [on the RPi 3] based on 64-bit ARMv8 architecture is backwards compatible with the Raspberry Pi 2 as well as the original. While the new CPU is 64-bit, the Pi retains the original VideoCore IV GPU which has a 32-bit design.”

I tested on a RPi3 and it works. However, the screen is blank and only the red PWR led is on, like you described. That could be fixed via kernel configuration, which I yet have to test. But I can log in via SSH, and at least the Ethernet interface, I2C bus and USB works.

Hi Michael, this look really cool. Can you maybe upload a .img on github or somewhere, that I can just copy to the SD card? I don’t have a spare computer to install debian on, and I’m trying to use virtualbox on my mac to follow the instructions, but I’m having trouble. Thanks

I actually could reproduce your issue on my RPi3. But increasing CONFIG_SYS_BOOTM_LENGTH to 64 MB does work. I updated the instructions above, and the README of the github repository. Don’t forget to run make clean before you recompile u-boot. It should work then.

Two more issues though:
It seems the variables for installing xfce directly into the image are ignored, i cant find any reference to xfce in the build.log and no xfce is present once booting the pi. The same is true for console keyboard config, the locale is not generated and the keyboard is not set even though i have included the mentioned settings. Thats a minor issue though.

Second and more seriously, once installing xfce and logging into the graphical interface the pi soon locks up hard, opening one or two windows is sufficient to break it.

I took out all desktop environment options from the script to keep everything minimal and simple. Installation of a desktop environment should be done manually – see “Install GUI” section above.

As to the hangups after any window is opened in XFCE, I experienced the same on both RPi2 and RPi3. I haven’t investigated what causes it, but I unplugged and re-plugged the USB keyboard and that seemed to fix it. It became responsive after about 10 seconds. It could be unrelated to USB though.

You need a kernel configuration file, without extra modules, but with all the required extensions. On other sites it is advised to take as a basis the settings from rpi2. Can you adapt and post it here?

I have a problem running current Debian Stretch with a vanilla kernel (4.10.10) on my RPi 2b

As soon as the vc4 drm gets initialized, the screen turns black. (using the composite out). I changed the kernel configuration to compile vc4 as a module and console stays available until I insmod “vc4”.

Just followed your README.md instructions and it works fine on an RPi3! Thanks SO MUCH!!! There are a couple of minor changes you might want to make to your README, but they didn’t throw me for a loop:

1. After telling people to become root to do the apt installs, you might want to tell them to go back to normal user mode before the git/build steps

2. After git clone git://git.denx.de/u-boot.git, you might want to add that they should cd into u-boot before doing git checkout

Hi Michael,
Thank you for the great instructions and the script. Debian is my operating system distribution of choice since 1995 (Linux since 1993, first TAMU Linux followed by SLS and Slackware). I got a Raspberry Pi 2 one or two years ago, but did not do much with it yet (using Raspbian so far).
I ran into 2 problems with the script:
First, the apt-get dist-upgrade command did not work. I am using an up-to-date Debian unstable as the host system; maybe it plays a role. I applied this patch:

Second, after copying the files to the SD card, u-boot.bin will not load anything further from the SD card, but it instead insists on booting via BOOTP and TFTP. This is obviously a dead end, because I only have a DHCP server running. This happens both with the confirmed working revision and with the newest one (commit 08546df976b79b1694af3ff12b26baf2931f371a). Which files could I check to make it work?

Regarding the –allow-unauthenticated switch, this seems to be specific to your host system. It should not be needed.

Regarding u-boot not loading the kernel, you should attach a monitor and keyboard to the Raspberry Pi and go into the u-boot interactive console, and try to boot manually to find out the problem. Probably something simple like a wrong filename.

Thank you again.
For some reason, some files in /boot/firmware/ had been omitted from the SD card. After adding those, the kernel will be loaded.

The next problem is that the network interface is not available. I am using Linux 4.11.7, and about 9 seconds into the booting, the LEDs on the Ethernet interface will light up, and a kernel message tells that eth0 was renamed into something. “ifup” does not recognize that string, and no IPv4 networking is working. I am not familiar enough with systemd to troubleshoot this, but I suspect that it could be some problem with the userspace.

The hardware should be OK, because when the files were missing U-boot did get a DHCP reply from the router.

According to the log files, there were some problems with some core package depencies.
I finally solved the problem by “debootstrap stretch /stretch” and rerunning the build script in that chroot, instead of running it in Debian Sid (unstable). Now everything works fine.
Lesson learned: Debian unstable is a too moving target for this kind of cross-platform development.

Above I give exact kernel/firmware/uboot git revision hashes. With newer/older revisions you’ll likely run into problems. Also compare checksums of the kernel, uboot and firmware files on the SD card and on the host system. Low quality SD cards and SD card readers may corrupt files, as well as improper unmounting.

Thanks for the howto. I was able to get (most) things working with some minor modifications ( –allow-unauthenticated for apt) and I think a “change directory (cd) command”. Nevertheless, bravo and thanks for the detailed tutorial.

I’ve got both an rpi2 and rpi3, but I’m currently attempting to get all the functionality on the rpi3 going.

I’m still unable to get the VC4 driver working. I see plenty of commentary on the internet about configuring an overlay in /boot/config.txt. Did you have to set anything in /boot/config.txt?

No, I didn’t have to add anything to config.txt. Only “avoid_warnings=2” is set on both Rpi2 and Rpi3. Make sure you check out the above quoted kernel, firmware and u-boot git revisions/hashes since I haven’t tested with any other revision since I wrote this article. VC4 should just work out of the box because it’s integrated into the upstream kernel.

Thanks for your work!
Two things:
1) just for the record: in recent kernel versions the SD/MMC host driver doesn’t detect the any card anymore, hence the kernel hangs forever while trying to mount the rootfs (hangs forever due to the “rootwait” command line parameter)
2) I just can’t get the kernel to recognise the sound HW. Did you do anything more than setting ‘CONFIG_SND_BCM2835_SOC_I2S’ to ‘y’?

You’re awesome! It worked, but only after i’ve added “–allow-unauthenticated” to the script ( gona fix keyring issue maybe, the proper way).

Any thoughts on how to boot kernel from apt repo via u-boot? Best scenario i see here is just trigger u-boot configuration generator (mkimage) after kernel update. That way i could easily compile new drivers on Pi directly.