From Gentoo Wiki
Jump to: navigation, search


The goal of these instructions is to have a running installation of Gentoo on a Cubox-i (this should also work on a SolidRun Hummingboard also), with a kernel up-to-date enough to run a current Btrfs root filesystem. Note Btrfs is not currently compatible with (kernel) gcc-plugins.


  • Cubox-i
    • if you want to configure over a serial console you need a CuBox-i2ultra or a CuBox-i4pro
    • otherwise you need an HDMI display and an USB keyboard
  • git
  • SD card (with enough space, boot partition, rootfs with a git kernel and Gentoo, 4GB+)
  • network cable for an internet connection (the WiFi driver needs a firmware that can be installed later)
  • another (Linux) computer with a cross compiler for arm installed (the installation for Gentoo is documented here)


If you want you can install the "Ignition" image of solid-run to see if your machine is working with the serial connection (or the connected keyboard and display). This will overwrite the U-Boot installation!


The install consists of installing sys-devel/crossdev, partitioning and formatting, the SD card. Copying over a stage3 tarball, configuring it so that it can boot and it can be accessed. Creating a kernel. Booting the kernel on the machine. Installing the kernel for an automatic boot. Continue a default Gentoo installation.

Installing Crossdev

This is necessary to build U-Boot and the kernel on your desktop system.

root #emerge sys-devel/crossdev
root #crossdev armv7a-hardfloat-linux-gnueabi

Details and troubleshooting are at the Embedded Handbook.

Setup U-Boot

When the Cubox-i was released there was no mainline support for it. So SolidRun maintained its own patched fork. Since 2017-01 a mainline U-Boot works without any patches, so there is no longer a real reason to go with the fork. For historic reasons the subtle differences in the installation of both configurations are shown.


user $export ARCH=arm
user $export CROSS_COMPILE=armv7a-hardfloat-linux-gnueabi-
user $git checkout v2017.01
user $cd u-boot
user $make mx6cuboxi_defconfig
user $make

A successful build will create two files in the source tree directory, SPL and u-boot.img

  • SPL file is the actual machine detection and initialization and must be flashed on offset 1 KByte of the boot SD card.
  • u-boot.img is the second stage bootloader; it can be flashed at offset 69 KByte from the starting of the boot SD card;
root # dd if=SPL of=/dev/sdX bs=1K seek=1
root # dd if=u-boot.img of=/dev/sdX bs=1K seek=69

In the mainline version there is no support for a uEnv.txt file without a patch. So you can use the legacy boot.scr method using u-boot-tools, or you can download a uEnv patch to provide more flexibility and easier configuration. The patch follows the usual LinuxOnArm wiki setup for deploying dtb files in versioned subdirectories similar to Wandboard:

U-Boot patch and SD card deploy steps:

Get the patch here:

More information:


SolidRun provides a custom U-Boot, this is a fork from the upstream and patched by Jon Nettelton. Main feature is addition of console on HDMI support, and the SPL support for Cubox-i. To build the bootloader, do:

user $export ARCH=arm
user $export CROSS_COMPILE=armv7a-hardfloat-linux-gnueabi-
user $cd u-boot-imx6
user $make mx6_cubox-i_config
user $make

A successful build will create two files in the source tree directory, SPL and u-boot.img

  • SPL file is the actual machine detection and initialization and must be flashed on offset 1KByte of the boot SD card.
  • u-boot.img is the second stage bootloader; it can be flashed at offset 42KByte from the starting of the boot SD card; or alternatively can be put as-is on the first partition of the SD card if the partition has a FAT filesystem.
root # dd if=SPL of=/dev/sdX bs=1K seek=1
root # dd if=u-boot.img of=/dev/sdX bs=1K seek=42

More information:

Setup serial console

The Cubox-i2ex, CuBox-i2Ultra and CubBox-i4Pro have serial console support via a FTDI FT230X USB to UART serial interface. This allows connecting the Cubox-i directly to another computer. Alternatively the Cubox-i can be connected to a HDMI display and USB keyboard.

The computer connecting to the Cubox-i will need to have the following kernel configuration options enabled:

KERNEL Enabling serial console support
    Device Drivers --->
      [*] USB support --->
            <*>   USB Serial Converter support --->
                    <*>   USB FTDI Single Port Serial Driver

Connecting to the serial console requires an application such as app-misc/screen or net-dialup/minicom. For more information refer to the SolidRun Wiki.

Preparing SD card

If the first test worked okay you can partition and format the card. As in the goal described in a two partition scheme will be used.

  • /dev/mmcblk0p1 will be ext2 with 100MB (boot)
  • /dev/mmcblk0p2 will be Btrfs with the rest of the capacity (root)

/dev/mmcblk0 can be different in your computer probably /dev/sdX

The minimal configuration of the root has to be done already on the other computer

  1. extract stage3
  2. edit /etc/fstab
  3. set root password
  4. enable serial console

Note: You can also make a single partition SD card with mainline U-Boot using ext2/3/4, however, for a Btrfs root (or other oddball filesystem) you'll need an ext boot partition and kernel support for your chosen filesystem.

Extract stage 3

Get the latest stage 3 and extract it to the root partition.

root #cd /mnt/sdcard-root
root #tar xvjpf /path/to/download/stage3-*.tar.bz2

Edit /etc/fstab

Edit on the root partition on the SD card /etc/fstab:

FILE /etc/fstab
/dev/mmcblk0p1          /boot           ext2            noauto,noatime  1 2
/dev/mmcblk0p2          /               btrfs           noatime         0 1

#/dev/SWAP              none            swap            sw              0 0
#/dev/cdrom             /mnt/cdrom      auto            noauto,ro       0 0
#/dev/fd0               /mnt/floppy     auto            noauto          0 0
With kernel 4.9.x or later use /dev/mmcblk1 instead of /dev/mmcblk0 (e.g. /dev/mmcblk1p1 is now the 1st partition on the SD card). The device names have changed with this kernel to accommodate another potential SD card.

Edit root password

To be able to login later we need to set a root password, we create password hash and edit it to the /etc/shadow.

root #openssl passwd -1
root #nano -w /mnt/sdcard-root/etc/shadow

Replace the star or current hash of the root user with the output from the command above.

Enable serial console

To also have a serial console after we booted the current system we need to modify.

root #nano /mnt/sdcard-root/etc/inittab

Change the s0 line to the following:

FILE /mnt/sdcard-root/etc/inittab
s0:12345:respawn:/sbin/agetty -L 115200 ttymxc0 vt100

This should be enough that a kernel can boot the system and that we can work with it afterwards.


At the moment the are multiple sources for kernels available all with their specific advantages and drawbacks.

If you are using the U-Boot from this wiki you can boot directly the zImage. It isn't necessary to convert it to a uImage.

Official (patched by SolidRun)

This is the current stable version: Most documentation will assume that you are running this kernel.

root #export ARCH=arm
root #export CROSS_COMPILE=armv7a-hardfloat-linux-gnueabi-
root #cd linux-imx6-3.14
root #make imx_v7_cbi_hb_defconfig
root #make menuconfig
root #make && make modules && make modules_install INSTALL_MOD_PATH=/path/to/image/

Vanilla (or Gentoo sources)

Vanilla kernel 3.19+ (and the gentoo-sources version) runs on the hardware complete with graphics and networking simply run

root #make imx_v6_v7_defconfig
root #make menuconfig

enable all the Atheros devices in Device Drivers > Network device support > Ethernet driver support then...

root #make

Kernel will be in arch/arm/boot/zImage and the the device tree will be in arch/arm/boot/dts/imx6dl-cubox-i.dtb (or imx6q-cubox-i.dtb , imx6dl-hummingboard.dtb etc...)

Latest patched version

  • These patches apply to the latest kernel. As of this writing you can apply them to sys-kernel/git-sources-4.1-rc1. Gentoo can do this automatically for you. Unzip the latest patch to /etc/portage/patches/sys-kernel/git-sources and create /etc/portage/bashrc as is documented here:
root #make imx_v6_v7_defconfig
root #make menuconfig

Create the zImage and the dtb file

root #make zImage
root #make imx6q-cubox-i.dtb
root #make modules
root #make modules_install

You can find other/more patches here: some


The drivers for WiFi need a firmware. In case you are have set them to built-in you have to include the blobs already in the kernel

The following settings are necessary for the driver:


I have the blobs from the GeeXboX package firmware-wifi-brcm80211_20161005+1-a179db979-2_armv7.opk

  • brcmfmac4329-sdio.bin
  • brcmfmac4329-sdio.txt

The files have to be dropped in /lib/firmware/brcm/ if the driver is compiled as module or directly into the kernel source folder under firmware/brcm if they will be compiled built-in.


To compile certain applications like Kodi that have modified/additional codecs you need to expose the patched kernel headers. Fortunately there is a script for that:

root #make headers_install ARCH=arm INSTALL_HDR_PATH=/usr/local/include

If you install them into /usr/local/include then you don't overwrite the ones provided by the Gentoo package.

Bootloader / U-Boot

U-Boot is quite flexible in the way it can start your kernel. A normal start will wait three seconds for an input. If a key is pressed an interactive shell is started and the boot is interrupted until the user chooses to boot. If the three seconds expire without input U-Boot will try to start with a default configuration. For this it will first check for a environment configuration. If you see a message like ** Warning - bad CRC, using default environment it means the no valid environment could be found and it continues with it hardcoded default. Here the mainline and SolidRun differ. Mainline expects a boot.scr on the first partition and SolidRun can work with a uEnv.txt on the first partition.

Mainline default

Using the mainline U-Boot uEnv patch cut from 2017.03, create uEnv.txt in your boot partition or directory:

FILE uEnv.txt

cmdline=video=HDMI-A-1:1024x768 net.ifnames=0 cma=384M console=tty1


Adjust the video argument to match your display.

SolidRun default

If you use the Soldidrun U-Boot from this wiki you can use the default settings and no direct modification of the U-Boot configuration might be necessary. If the first partition of the SD card is formatted with ext2 or fat it will read the the file uEnv.txt with the configuration from it.

FILE uEnv.txt
mmcargs=setenv bootargs root=/dev/mmcblk0p2 rootfstype=btrfs rootwait rootflags=compress console=ttymxc0,115200n8 video=1920x1080M@60 init=/sbin/init

These two lines should be enough to boot the kernel. The U-Boot from this wiki can boot a zImage directly (no conversion to uImage necessary). The zImage and the *.dtb file have to reside in the root folder of this partition next to the uEnv.txt. The second line contains the kernelflags (for example the root).

If you have no console output on your screen during boot, try console=tty1

With 4.9.x kernel or later use /dev/mmcblk1 instead of /dev/mmcblk0. In the above example, change the root= line to root=/dev/mmcblk1p2 to inform the kernel that the root partition is the 2nd partition on the /dev/mmcblk1 device.


Connect to your Cubox-i with a serial console (or with a keyboard and a display) and interrupt the U-Boot bootloader with Enter and type the following commands.

setenv ipaddr 192.168.0.<CUBOXI-IP>
setenv serverip 192.168.0.<TFTP-IP>
setenv bootargs root=/dev/mmcblk0p2 rootfstype=btrfs ro rootwait console=ttymxc0,115200
tftpboot 0x10800000 uimage
bootm 0x10800000

This should boot you in your Cubox-i installation and you should be able to login as root with your password. From here you can continue with a default Gentoo installation. To make this boot configuration permanent follow the next step "Default".


In the following we will make the settings permanent. The uImage file is copied to the boot partition. The first line contains the settings for loading the kernel into memory. The second holds the arguments for the kernel. The third one is the code to execute the kernel.

The bootcmd is called by default and executes theses three steps in order. The last line makes these variables permanent in the U-Boot settings.

setenv mybootload ext2load mmc 0:1 0x10800000 /uimage
setenv mybootset setenv bootargs root=/dev/mmcblk0p2 rootfstype=btrfs ro rootwait console=ttymxc0,115200
setenv mybootstart bootm 0x10800000
setenv bootcmd run mybootset mybootload mybootstart


U-Boot can also read configuration values from a file. This way the boot process can be modified without going into the U-Boot console and the settings are permanent as well. The following script is modified from the original mini-image used for the installation.

setenv gsetmmc 'root="root=/dev/mmcblk${rootunit}p$rootpart rootfstype=$rootfs ro rootwait"' 
setenv gconsole console=ttymxc0,115200 consoleblank=0
setenv gbootextra init=/init
setenv grootflags ""
setenv gvideo mxcfb0:dev=hdmi,1920x1080M@60,if=RGB24 dmfc=3
setenv gbootpreset 'bootdev=mmc; bootunit=0; bootpart=1; bootfs=ext2; envfile=uEnv.txt; bootroot=; bootfile=uImage'
setenv grootpreset 'rootunit=0; rootpart=2; rootfs=btrfs'
setenv gsetenvscript setenv gbootenv "\'run gset\${bootdev}; setenv bootargs \$root \$gvideo \$gconsole \$gbootextra \$grootflags $end\'"
setenv gloaduenv 'if ${bootfs}load $bootdev $bootunit:$bootpart $loadaddr $envfile; then env import -t $loadaddr $filesize; fi'
setenv grootpresetup 'bootrun=bootm; loadfile=$bootfile; rootdev=$bootdev; rootunit=$bootunit; rootpart=$rootpart; rootfs=$rootfs'
setenv gbootload '${bootfs}load $bootdev $bootunit:$bootpart $loadaddr $bootroot/$loadfile'
setenv gbootstart '$bootrun'
setenv bootcmd run gbootpreset grootpreset gsetenvscript gloaduenv grootpresetup gbootenv gbootload gbootstart

In the minimal uEnv.txt is enough to boot a stock ext4 system on the SD card. To boot from USB you must use rootwait or rootdelay.

Continue Gentoo install

Steps that should be done right after the installation

  1. setup network
  2. set date
  3. emerge-webrsync
  4. emerge ntpd
  5. /etc/init.d/sshd

Gentoo arm install Handbook

Graphics driver (closed source)

You can find a portage repository with packages for the closed source drivers on github:

Graphics drivers (FOSS)

Although it's not fully integrated yet, there is useful 2D/3D functionality in the latest FOSS drivers, some of which were only recently added to the Gentoo ARM overlay.

  • mesa - the latest releases enable vivante/imx (be sure and enable gallium/glx/dri3 in mesa)
  • libdrm - enables "experimental" vivante/etnaviv api
  • xf86-video-armada - builds multiple drivers, depends on various versions of dependencies below
  • libdrm-armada - gpu shim
  • libetnaviv (latest is header-only, older is a library)
  • galcore-headers - public "etnaviv" interface

Note: the packages in the main portage tree call the imx VIDEO_CARD "vivante" but in the above Xorg drivers vivante refers to the legacy GAL drivers which are disabled (the FOSS pieces should probably all be called etnaviv). To try the FOSS graphics stack, you should set VIDEO_CARDS="imx vivante" in your make.conf file and add the ARM overlay.

So far the imx/armada drivers seem to work for 2D in X but the log shows an error initializing the etnadrm_gpu driver and claims to fall back to swrast 3D. Still, with dri3 and vivante enabled glxgears gets over 110 fps in Xorg, so there is that... (if you only have dri2 enabled then it really is swrast @ 22 fps)


In addition to enabling the Freescale PCIe driver and related SD support, if you want to connect an external eSATA device, there are two main "issues" to keep in mind:

  • Use a separate USB power source, since there is no power provided over eSATA (and the onboard USB is not enough)
  • You must add ahci_imx.hotplug=1 to the kernel command line in uEnvt.txt (or your boot.scr)



If you want to install Kodi make sure that:

  • consoleblank=0 is enabled in the bootargs otherwise you will get a "No signal/no video" after 10 minutes
  • for the moment you should use Kodi and libCEC from the custom repos
  • you have make headers_install executed


Open questions