From Gentoo Wiki
Jump to:navigation Jump to:search

A short set of notes for working with embedded disk images on Linux, specifically Build.Dist disk images produced by the GenPi64 project. It is easy to use a more powerful machine in order to operate on disk images.


Download, extract, and mount image

As of the present, the community ran GenPi64 project produces zstd compressed .img files. In order to actively work with one of these images, a few setup steps are necessary.

Download the image from

user $wget --continue <URL

Extract the image to a work area. Tips this can be in zram, tmpfs, or the generic filesystem.

root #zstdcat /path/to/genpi64-lite.img.zstd > /path/to/workdir/genpi64-lite.img && sync

Follow the extraction by mounting the image using losetup. If everything goes well and there are no other loop devices mounted, the output of the command will be /dev/loop0:

root #losetup --partscan --find --show genpi64-lite.img

Long listing the device will show all available partitions for the loop mounted image. For GenPi64 the output should look like the following:

user $ls -l /dev/loop0*
brw-rw---- 1 root disk   7,  0 Jan 18 15:15 /dev/loop0
brw-rw---- 1 root disk 259, 10 Jan 18 15:15 /dev/loop0p1
brw-rw---- 1 root disk 259, 11 Jan 18 15:15 /dev/loop0p2

Finally, create mount points if necessary and mount the partitions:

root #mkdir --parents /srv/genpi64
root #mount /dev/loop0p2 /srv/genpi64 #btrfs rootfs
root #mount /dev/loop0p1 /srv/genpi64/boot #vfat boot


pychroot tends to save a few steps in mounting all the virtual file systems.

root #pychroot /srv/genpi64

Alternative mound (without pychroot):

root ##todo


Follow the guide from the Raspberry Pi Foundation for compiling the kernel. At the time of this writing, compilation for the Raspberry Pi 4 looks like:

root #cd /usr/src/linux
root #KERNEL=kernel8
root #make -j4 ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcm2711_defconfig


Writing the image

Generally the image will be written to a microSD card via mmc connection:

root #zstdcat genpi64-lite.img.zst > /dev/mmcblk0 && sync

Finishing up

root #umount --detach-loop /srv/genpi64/boot #vfat boot
root #umount --detach-loop --lazy --recursive /srv/genpi64 #rootfs

Tips and tricks

Custom kernel compiling

Download a branch of the Raspberry Pi Foundation sources from GitHub. For this example rpi-5.11.y will be used:

root #git clone --branch rpi-5.11.y /usr/src/raspberrypi-sources
root #ln -s /usr/src/raspberrypi-sources /usr/src/linux

Modify the kernel following the directions on

After modifying the kernel, manually tweak the CONFIG_LOCALVERSION configuration value so that the installed modules do not clobber existing modules in /lib/modules/:


Appending the suffix -p4 specifies the build is for the Pi 4.

CPU frequency scaling

Being a general purpose device, the base clock of the Rpi 4 is 700 MHz, however the clock speed should scale as appropriate for the duties performed. Here are a few tips to help adjust from the alpha5 GenPi64 base image:

  • Change the default CPUfreq governor from powersave to ondemand.
    • Install sys-power/cpupower
    • Set the governor to ondemand: cpupower frequency-set --governor ondemand
    • Measure CPU frequency speed with: watch -n 1 vcgencmd measure_clock arm
  • Overclock the ARM core to at least 1200 MHz via config.txt. Default arm_freq value for the Rpi4 is 1500 according to this list.

Bootloader firmware update

It is wise to check the firmware for updates every few months:

root #rpi-eeprom-update

Known issues and workarounds