Udoo



This document is both a mainline integration story and a description of how to install Gentoo using mainline u-boot and kernel plus FOSS graphics on the Udoo Quad and Dual kickstarter boards. See this gist for a quick and dirty howto on Udoo Neo (note that mainline kernel still has barebones DTS files for Neo boards, no HDMI output, etc).

Prerequisite

 * Udoo Quad/Dual
 * if you want to configure over a serial console you need a micro-USB cable.
 * otherwise you need an HDMI display and a USB keyboard (and hope ;)
 * git
 * SD card (with enough space, rootfs with a kernel and Gentoo, 4GB+)
 * network cable for an internet connection (the WiFi driver should actually work with a newer kernel)
 * another (Linux) computer with a cross compiler for arm installed (the installation for Gentoo is documented here)

Optional
If you want you can install the Udoobuntu image to see if your machine is working with the serial connection (or the connected keyboard and display). This will overwrite your card!
 * tftp server
 * Udoobuntu
 * Udoobuntu

Installation
The install consists of installing, partitioning and formatting, the SD card. Copying over a stage3 tarball, configuring it so that it can boot and it can be accessed. Building U-Boot and 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.

For more details, please refer to the Embedded Handbook and Crossdev articles.

Setup U-Boot
When the Udoo was released there was no mainline support for it. So the vendor maintained its own patched fork of bootloader and kernel. That said, since 2014.04 a mainline U-Boot works without any patches, so there is no longer a real reason to go with the fork. Just use mainline (and possibly some RCN convenience patches).

If you're already familiar with the LinuxOnArm wiki approach and like the convenience of uEnv.txt configuration, then you can download and apply the optional patch below.

Mainline
A successful build will create two files in the source tree directory, and


 * file is the actual machine detection and initialization and must be flashed on offset 1 KByte of the boot SD card.
 * is the second stage bootloader; it can be flashed at offset 69 KByte from the starting of the boot SD card;

In the mainline version there is no support for a file without a patch. So you can use the legacy 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, which is the default kernel make install path:

U-Boot patch and SD card deploy steps: https://eewiki.net/display/linuxonarm/UDOO#UDOO-Bootloader:U-Boot

Get the patch here: https://dev.gentoo.org:/~nerdboy/files/0001-udoo-uEnv.txt-bootz-n-fixes-ala-rcn-2017.11.patch

More information: http://www.denx.de/wiki/U-Boot

Setup serial console
The Udoo Quad/Dual boards all have serial console support via a FTDI FT230X USB to UART serial interface. This allows connecting the Udoo directly to another computer. Alternatively the Udoo can be connected to an HDMI display and USB keyboard.

The computer connecting to the Udoo will need to have the following kernel configuration options enabled:

Connecting to the serial console requires an application such as or. For more information refer to the.

Note with U-Boot uEnv.txt patch above, you can make the sdcard a single ext4 partition with /boot directory instead of the two partitions shown below. The patch also allows you to change the rootfs via the "mmcroot" variable.

Preparing the SD card
As noted above, 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.

Extract stage 3
Get the latest stage 3 and extract it to the root partition:

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

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.

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  line to the following:

Mainline (or Gentoo sources)
The mainline kernel 3.19+ and has great support for Udoo devices, complete with working graphics and networking.

Create the install directories:

Setup the cross-compilation environment:

Configure the kernel:

Build and install the kernel (zImage):

The kernel is located at. The kernel will be installed at

Build and install the kernel modules:

The kernel modules will be installed at

Build and install the device trees:

The device trees are located at. The device trees will be installed at

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

Latest patched version

 * These patches apply to the latest kernels. As of this writing you can apply them to sys-kernel/git-sources-4.xx or the matching gentoo-sources. Gentoo can do this automatically for you. Unzip the latest patch to  and create  as is documented here: https://wiki.gentoo.org/wiki//etc/portage/patches.

Create the zImage and the dtb file

You can find the individual patches here: latest patches for OMAP, iMX, and other devcices

Kernel Sources Summary:


 * gentoo-sources (or mainline vanilla)
 * works, but is missing specific fixes and device features
 * armv7-multiplatform (mainline with embedded patches)
 * cross-arm kernel build scripts (not an ebuild)
 * includes lots of device fixes/patches plus baseline defconfig
 * armv7multi-sources (arm overlay, latest is 4.17.7-r8)
 * same as gentoo sources plus patch from armv7-multiplatform, plus extra patches
 * in particular, the udoo serial/arduino patches for uploading firmware

WiFi
The following kernel configuration options are required for WiFi support. These options should already be enabled if the kernel was configured with  or the armv7-multiplatform config.

Install the sys-kernel/linux-firmware and net-wireless/wpa_supplicant packages and you should be all set.

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 Udoo U-Boot differ. Mainline supports and extlinux.conf on the first partition, and it also supports  with the patch. The Udoo version of u-boot-imx supports both methods natively.

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

extlinux.conf
Vanilla U-Boot also 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 or applying patches to add  support.

Create the directory:

Create the following configuration and adjust accordingly:

Adjust the video argument to match your display.

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 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  in your  file and add the ARM overlay. Also note that  has been removed in Xorg 1.20 and above.

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)

Sam3 Microcontroller (Arduino Due compatible)
The main "thing" about Udoo boards is that they have a built-in Arduino-compatible ARM cortex-M microcontroller. The original Udoo Quad/Dual boards have an Atmel Sam3 (equivalent to a Cortex-M3, no FPU) connected directly to the i.MX ARM via serial (ttymxc3 on the ARM side). This can be adjusted via a jumper on the board. As of the 4.14 mainline kernel there is a new imx-rproc driver similar to the BeagleBone PRU drivers (as well as the rpmsg char interface).

You can use the latest crossdev-99999999 to build a multilib arm-none-eabi toolchain for ARM embedded processors; currently gcc 5.4.0_r4 and 6.4.0 in the ada-overlay have some extra patches for armv8-M and somewhat saner support for thumb/hardfloat/softfloat but it should be possible with the current versions in the main Portage tree. Without the extra patches, you should add "--with-multilib-list=aprofile" to EXTRA_ECONF on your crossdev command, and for bare metal toolchains you should also add USE="-nptl -sanitize -vtv".

Hardware Random Number Generator
The FSL/NXP i.MX6 boards have a hardware random number generator.

All of the Freescale CAAM kernel options should be enabled as modules (built-in may have trouble with rngd).

Driving /dev/random with the hardware CAAM module is done via the following steps.

Apply settings in /etc/conf.d/rngd
Add the following to /etc/conf.d/rngd

Check that /dev/random is slow
To verify that we have done everything correctly, open a new terminal and do: It will start displaying gibberish (random) but will stop at some point or at least slow down. Now issue CTRL+C to stop it.

Test if it works
Again, issue: in another terminal. Now the random information should be flowing faster than the first time around. Now issue CTRL+C to stop it.

Using the kernel entropy source (a USB keyboard attached, display connected) /dev/random spews approx. 100 "chars" of random information before it blocks. After loading the module and starting rng-tools, it should print out many lines without blocking.

Add rng-tools to boot
If all is good, add rngd to boot.

Add loading of caamrng to boot
Add the following to /etc/conf.d/modules so that the modules get loaded at boot

Applications
The main application of "concern" for Udoo quad/dual boards is a functioning Arduino core + IDE so sketches can be compiled and uploaded to the sam3 as expected. In this case upstream maintains their own forks of both the Arduino IDE and bossac uploader, and it's all tied together with their vendor kernel forks. This needs several patches on both the kernel and application side, so there are corresponding overlays required to get all the right bits:


 * arduino overlay - ebuilds for arduino 1.8.5 and bossa 1.3 (USE=udooqdl)
 * arm support overlay - kernel ebuilds with patches for arduino manager and dts

Note that crossdev-99999999 is also required for basic cortex-M multilib support, and you will also probably want to set the multilib-list configure option for gcc (see below).

An optional overlay contains ebuilds and patches for Ada language support in the toolchain, as well as gcc-6.4.0 patches for amrv8-M support (not required for Udoo).


 * ada toolchain overlay - ebuilds/eclass with Ada language and armv8-M patches. Note that if you want to build your cross toolchain with Ada support you must first (re)build your system gcc with USE="ada." See the overlay readme for details.

Arduino IDE


Due to the way the hardware is integrated, including shared pins and a dedicated serial interface between the ARM side and the sam3 side, the arduino IDE takes several Udoo-specific patches. All of them are required, including kernel/dts patches, arduino board patches, and a patched version of the bossa upload tool. The following packages and USE flags will pull all the right integration bits.

First build your favorite light-weight desktop (eg, lxqt) and use or  to add the arduino-overlay and arm overlay. Make sure you're running the latest armv7multi kernel with arduino patches, then get rid of old icedtea-7 and install icedtea-8 and crossdev-99999999. Use crossdev to build the arm-none-eabi toolchain.

The desktop pic shows the arduino IDE after uploading one of the example sketches that reads characters from the IDE serial console (sorry no blinky lights). Note you need to select the port as well as the board.

eselect repository
Install and  if they do not yet exist:

Add and sync the extra overlays with these commands:

Layman
Install layman with the portage sync bits:

For "unofficial" overlays, make layman happy by adding the repository URLs to the layman config file:

Then sync layman and add both repositories one at a time (say "y" at the prompt).

Required Packages
For arduino to work, you need either armv7multi-sources-4.14.5-r2 or armv7multi-sources-4.14.6-r2.

Default USE flags for icedtea should be fine.

For arduino 1.8.5 you need USE="udooqdl" and it should pull in bossa 1.3 which has the Udoo sam3 upload patches.

Finally, for the toolchain you want crossdev-99999999 and something like this crossdev command:

If all goes well (and it should) you will see a new entry in your list of system compilers:

Check your available multilib targets:

Required Devices
Since this is an embedded device, you get bonus tty devices with funky names (yay!). In the case of Freescale/NXP they are mostly of the form ttymxcN where N is 1-9. By default on imx6 there is usually ttymxc0 or ttymxc1 for the serial console, which on Udoo quad/dual boards is one of the micro-USB connectors. The sam3 "arduino" part requires a second ttymxc3 serial port (which is enabled by a kernel patch) and a special device (also enabled by a kernel patch) to allow the uploader to control the port on the arduino (see below). The latter two devices require user-level permissions for the IDE, so we'll use the usual uucp group udev rules.

If you're running the patched kernel, you should see the following devices after boot-up:

For the right permissions, udev defaults need to be changed; for now you can edit the default serial rules and add the following:

Make sure you are in the uucp group, and after "udevadm trigger" or a reboot, the device permissions should be:

Other than possibly a transient error if you open the IDE serial console right before it starts to flash, the arduino IDE should now be able to upload firmware with the default "upload" button. If you get an error message in the IDE about "can't erase/reset device" and the above output looks good, then make sure you emerged the arduino IDE and kernel sources with USE="udooqdl" and your version of bossa is 1.3.