Optional

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!

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.

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.

NoteOne difference is the offset where the u-boot image has to be flashed.

Mainline

user $export ARCH=arm

user $export CROSS_COMPILE=armv7a-hardfloat-linux-gnueabi-

user $git clone http://git.denx.de/u-boot.git

user $cd u-boot

user $git checkout v2017.01

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:

SolidRun

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 $git clone https://github.com/SolidRun/u-boot-imx6.git

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.

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:

Preparing the SD card

Partition

Filesystem

Size

Description

/dev/mmcblk0p1

ext2

100 MB

Boot partition

/dev/mmcblk0p2

ext4

Rest of SD card

Root partition

NoteWith kernel 4.9.x or later use /dev/mmcblk1 instead of /dev/mmcblk0 (i.e. /dev/mmcblk1p1 will be the first partition on the SD card). The device names have changed to to accommodate another potential SD card.

A single partition scheme can be used with mainline U-Boot when using an ext2/3/4 formatted root partition. However when using a Btrfs formatted root partition (or other unsupported filesystem), an ext2/3/4 or fat32 formatted boot partition is required.

Set the 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 the serial console

To have a serial console available after booting, change the s0 line to the following:

FILE/mnt/sdcard-root/etc/inittab

s0:12345:respawn:/sbin/agetty -L 115200 ttymxc0 vt100

Kernel

Mainline (or Gentoo sources)

The mainline kernel 3.19+ and sys-kernel/gentoo-sources has great support for Cubox-i devices, complete with working graphics and networking.

Create the install directories:

root #mkdir -p /var/build/cubox-i/root/boot

NoteThe install directories are where the kernel, modules and devices trees will be installed. In this article /var/build/cubox-i/root is used as an intermediate root directory. Any directory can be used, even the actual root directory of the device.

Setup the cross-compilation environment:

root #export ARCH="arm"

root #export CROSS_COMPILE="armv7a-hardfloat-linux-gnueabi-"

root #export INSTALL_PATH="/var/build/cubox-i/root/boot"

root #export INSTALL_MOD_PATH="/var/build/cubox-i/root"

Configure the kernel:

root #cd /path/to/kernel/source

root #make imx_v6_v7_defconfig

root #make menuconfig

Build and install the kernel (zImage):

root #make zImage

root #make zinstall

The kernel is located at arch/arm/boot/zImage. The kernel will be installed at /var/build/cubox-i/root/boot/vmlinuz-<kernel-version>

Build and install the kernel modules:

root #make modules

root #make modules_install

The kernel modules will be installed at /var/build/cubox-i/root/lib/modules/<kernel-version>/

Build and install the device trees:

root #make dtbs

root #make dtbs_install

The device trees are located at arch/arm/boot/dts/. The device trees will be installed at /var/build/cubox-i/root/boot/dtbs/<kernel-version>/

NoteThe above will build and install device trees for all i.MX devices. It is possible to build a device tree for a specific device only. For example, run make imx6q-cubox-i.dtb to build the device tree for a Cubox-i4Pro. The device tree will be located at arch/arm/boot/dts/imx6q-cubox-i.dtb, and needs to be copied manually to /var/build/cubox-i/root/boot/dtbs/<kernel-version>/

The kernel, modules and devices trees can now be installed to the actual root directory of the device:

root #cp -r /var/build/cubox-i/root/ /path/to/actual/root

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: https://wiki.gentoo.org/wiki//etc/portage/patches.

The WiFi driver requires firmware to operate, which can be obtained directly from the Linux firmware repository or the sys-kernel/linux-firmware package. The required firmware can be determined by examining the dmesg output of a running Cubox-i device:

The above output from a Cubox-i4Pro indicates that brcmfmac4330-sdio.bin is the firmware required by the driver. This may be differ depending on the Cubox-i model.

The firmware also requires NVRAM calibration data, which can be obtained from the Freescale (now NXP) repository. The NVRAM calibration data needs to have the correct WiFi regulatory domain set. This can be done by setting the value of the ccode parameter to the country code in which the device will be operating in. For example, to set the WiFi regulatory domain for the United States:

FILEbrcmfmac4329-sdio.txt or brcmfmac4330-sdio.txt

ccode=US

The firmware and NVRAM calibration data need to be placed in the /lib/firmware/brcm directory.

Headers

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:

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

Bootloader

U-Boot will normally wait three seconds for user input before attempting to boot. If user input is received, the boot sequence is interrupted and an interactive shell is started. If three seconds pass with no user input, U-Boot will look for an environment configuration on the first partition. If no valid environment configuration is found, U-Boot will display *** Warning - bad CRC, using default environment, and will then continue with the default environment configuration. This is where mainline U-Boot and SolidRun U-Boot differ. Mainline supports boot.scr and extlinux.conf on the first partition, while SolidRun also supports uEnv.txt.

Mainline

extlinux.conf

U-Boot supports Syslinux style boot configuration. U-Boot only borrows a small subset of the Syslinux configuration options, and does not require Syslinux itself. This is much simpler than using boot.scr or applying patches to add uEnv.txt support.

SolidRun

uEnv.txt

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.

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

NoteWith 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.

Interactive

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.

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".

Environment

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.

uEnv

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.

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)

eSATA

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)

Applications

Kodi

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