[[PageOutline]]

= Ubuntu on Ventana=

While Gateworks cannot fully support all Linux distros, it is relatively simple to
overlay a Gateworks Ventana kernel onto any non-Gateworks third party Linux distro
rootfs image. For a full list of Linux BSP's for Ventana see [wiki:ventana#bsp
here]

This page is dedicated details regarding running Ubuntu on an Gateworks Ventana

Board.

For a full Board Support Package providing building a Linux distro from source,
please see the OpenWrt, Yocto, or Android BSP from the [wiki:ventana#bsp Ventana
BSP] page

See also:
* The Gateworks Ventana [wiki:ventana#third_party_linux third party linux] page
for more details on how to use other linux distro on Ventana.
* [wiki:/ubuntu Gateworks Ubuntu Page for general notes]

[=#prebuilt]
== Gateworks pre-built Ubuntu Disk Images ==
Gateworks provides a pre-built Ubuntu firmware images for the Ventana Family:
* Compressed Disk Image containing boot firmware, kernel and root filesystem
'''(Recommended for microSD / eMMC booting)'''
- [http://dev.gateworks.com/ventana/images/focal-ventana.img.gz focal-
ventana.img.gz]
- To update the firmware on a microSD card see
[wiki:linux/blockdev#UsingaDiskImage]
* UBI images '''(Recommended for RAW NAND FLASH booting)'''
- [http://dev.gateworks.com/ventana/images/focal-ventana_normal.ubi focal-
ventana_normal.ubi] - UBI image for 2K page size 'normal' geometry FLASH
- [http://dev.gateworks.com/ventana/images/focal-ventana_large.ubi focal-
ventana_large.ubi] - UBI image for 4K page size 'large' geometry FLASH
- see [wiki:/linux/ubi/#flashgeometry here] to determine your flash geometry
- see [wiki:/linux/ubi#BasicMethod here] for info about flashing UBI images
* [http://dev.gateworks.com/ubuntu/focal/focal-ventana.tar.xz focal-armhf.tar.xz]
- tarball of rootfs (not including kernel) you can use to image onto microSD /
mSATA. See [wiki:linux/blockdev linux/blockdev] for instructions
* [http://dev.gateworks.com/ventana/images/linux-ventana.tar.xz linux-
ventana.tar.xz] Kernel, device-tree, bootscript, and modules that can be combined
with a root filesystem to create a bootable system. See [wiki:linux/blockdev
linux/blockdev] for instructions

'''Login Information (default)'''

* Username: root
* Password: root

Features:
- Ubuntu arm core (created via [https://github.com/gateworks/ubuntu-rootfs ubuntu-
rootfs.sh] debootstrap script)
- Gateworks Ventana Linux kernel (Linux 5.4 based)
- eth0 dhcp with a 30 second timeout
- User: root password: root
- Packages installed on top of core including:
* Updated modemmanager/libqmi-utils/libmbim-utils (see [wiki:ubuntu#modem
ubuntu/modem])
 * Misc wireless: wpasupplicant iw
* Misc utils: vim can-utils i2c-tools usbutils pciutils screen watchdog binutils
* Misc network: wget ethtool iperf iperf3 openssh-server iptables
* Linux firmware
* mmc-utils from https://packages.debian.org/sid/utils/mmc-utils
* Gateworks [https://raw.githubusercontent.com/Gateworks/meta-
gateworks/master/recipes-support/hostapd-conf/hostapd-conf/hostapd-conf hostapd-
conf script]
* Filesystem tools: e2fstools parted
- first-boot script to grow root filesystem partition and filesystem (useful when
putting disk images on removable storage devices)
- use ifupdown tools instead of netplan (we find them easier to understand and
configure)

[[CollapsibleStart(Old Releases)]]
Old Releases:
* Ubuntu 16.04 LTS (Xenial Xerus) console image
- Important Notes:
- This is a mainline kernel that does not have Video Hardware Acceleration
support for gstreamer and a few other Gateworks specific items. For more
information, read [wiki:ventana#MainlineLinuxKernelsupport Gateworks Mainline Linux
Support].
- This requires the latest Gateworks Bootloader - U-Boot v2017.05 (see
http://dev.gateworks.com/ventana/images and
http://trac.gateworks.com/wiki/ventana/bootloader#PreBuiltBootloader)
- A pre-built console image created using the [#debootstrap debootstrap] method
for [http://releases.ubuntu.com/16.04/ Ubuntu 16.04 (Xenial Xerus)] can be
downloaded:
* [http://dev.gateworks.com/ventana/images/xenial-ventana_normal.ubi xenial-
ventana_normal.ubi] - UBI image for 2K page size 'normal' geometry FLASH (see
[wiki:/linux/ubi/#flashgeometry here] to determine your flash geometry)
- see [wiki:/linux/ubi#BasicMethod here] for info about flashing UBI images
- sha256sum: 000c3fb814f1c0605dd904cab1b77131a5a69e72a145158685d402f0f03aedbf
* [http://dev.gateworks.com/ventana/images/xenial-ventana_large.ubi xenial-
ventana_large.ubi] - UBI image for 4K page size 'large' geometry FLASH (see
[wiki:/linux/ubi/#flashgeometry here] to determine your flash geometry)
- see [wiki:/linux/ubi#BasicMethod here] for info about flashing UBI images
- sha256sum: 590b4bc6af10fd8ff07061e73479fc5511fbe718a8b20e16cc6d9051e3ae5151
* [http://dev.gateworks.com/ubuntu/xenial/xenial-armhf.tar.xz xenial-
armhf.tar.xz] - tarball of rootfs you can use to image onto microSD / mSATA
- see [wiki:linux/blockdev linux/blockdev] for instructions
- sha256sum: a03dede35c64a8e28a71279b262ae9092a29ca8fd7de0e09faba4c6cc1f1356b
- Features:
- Ubuntu 16.04 (from debootstrap instructions)
- Ubuntu Xenial kernel (Linux 4.11 based) with drivers/firmware
- custom bootscript supporting NAND/UBI, MMC, SATA, USB boot devices and root
filesystems
- extra packages: openssh-server can-utils i2c-tools usbutils pciutils
- eth0 dhcp
- user root passwd root

[[CollapsibleEnd]]

[=#rootfs]
[=#debootstrap]
== Building the Root Filesystem via debootstrap
A popular way to create a Ubuntu root filesystem is to use the {{{deboostrap}}}
utility on a Debian or Ubuntu host. This tool provides a 2-stage install where the
second stage is within a chroot environment using qemu-arm.

Gateworks uses a script to do this which you may find at

http://github.com/Gateworks/ubuntu-rootfs

Requirements:
- Linux Ubuntu or Debian System with network connection and sudo permissions
- Linux Kernel
- Ventana target board with bootloader
- Boot device with 2GB+ of free space (micro-SD, USB mass storage, mSATA, 1GB/2GB
NAND flash)

Important notes:
* These steps are not always exactly what we do in our script but give you an idea
of how you would go about doing it yourself if you wanted to customize something
* We set and use '''target''' and '''distro''' env variables in step 2 and use
those env variables in the remaining steps to make this tutorial more version-
agnostic. Please be aware of this and do not deviate from the steps unless or until
you completely understand what you are doing.
* While operating under the qemu chroot (ie on the host system) you may encounter
'qemu: Unsupported syscall'. Note that messages from QEMU about unsupported
syscalls are often harmless, because typically they only appear for relatively new
syscalls which QEMU hasn't implemented yet. The guest code will have a fallback
path so it works on older kernels which don't implement the syscall, so a message
is printed but the application still runs. So if the guest program is failing then
it is quite likely to be for an entirely unrelated reason to the missing syscalls.

Host specific notes:

* Ubuntu 16.04:
- **qemu: Unsupported syscall: 373**: an [https://salsa.debian.org/kernel-
team/initramfs-tools/commit/b4804dd update] to initramfs-tools adds a 'sync -f'
which isn't supported on qemu-2.5 used by Xenial 16.04. This is fixed in qemu-2.11
(used on Ubuntu 18.04 and beyond). This will cause initramfs updates to fail which
may be used if you are trying to use a kernel needing an initramfs. To work around
the issue you can comment out the 'sync -f' call in update-initramfs:
{{{#!bash
sed -i 's/sync/#sync/' /usr/sbin/update-initramfs
dpkg --configure -a # re-run any halted postinst scripts
}}}

Steps:
1. Install pre-requisites:
{{{
#!bash
sudo apt-get install qemu-user-static debootstrap binfmt-support
}}}

2. Perform first stage install of minimal filesystem:

{{{
#!bash
target=rootfs
distro=focal
sudo debootstrap --arch=armhf --foreign $distro $target
# copy qemu-arm-static binary for the binfmt packages to find it and copy in
resolv.conf from host
sudo cp /usr/bin/qemu-arm-static $target/usr/bin
}}}
* See http://ports.ubuntu.com/ubuntu-ports/dists/ and
https://wiki.ubuntu.com/Releases for a list of Ubuntu releases. For example:
20.04=focal (latest LTS)
* this minimal rootfs is still missing some core packages and configuration before
it can be booted. These steps are taken care of in a 2nd stage install within a
chroot shell
* the chroot shell below will provide network support (inherited from the host)

3. we now have a minimal Ubuntu rootfs - chroot to it and perform the 2nd stage
install:
{{{
#!bash
sudo chroot $target
# now we are in the chroot
distro=focal
export LANG=C
# setup second stage
/debootstrap/debootstrap --second-stage
}}}
* this is the most minimal rootfs we would recommend

4. (optional) add additional apt package repos:

{{{
#!bash
cat <<EOT > /etc/apt/sources.list
deb http://ports.ubuntu.com/ubuntu-ports $distro main restricted universe
multiverse
deb http://ports.ubuntu.com/ubuntu-ports $distro-updates main restricted universe
multiverse
deb http://ports.ubuntu.com/ubuntu-ports $distro-security main restricted universe
multiverse
EOT
}}}
* you may want to customize the above list, depending on your needs. See
[#packages below] for more detail on Ubuntu package feeds

5. (optional) update package database and setup locales (do not skip this step if
you are needing to install any packages for the steps below or otherwise)
{{{
#!bash
apt-get update
apt-get -f install # fixup missing package dependencies
apt-get install locales dialog
dpkg-reconfigure locales
}}}

6. set hostname:
{{{
#!bash
echo ${distro}-armhf > /etc/hostname
}}}

7. create a default fstab:

{{{
#!bash
cat <<EOT > /etc/fstab
/dev/root / auto defaults 1 1
EOT
}}}
* Note that this not required if you pass in 'rw' on the kernel cmdline. However
while that is the default for the Ventana bootscripts for removeable storage it is
not for NAND boot, therefore we will add a default fstab that will re-mount the
kernel mounted rootfs as read-write
* /dev/root in /etc/fstab will refer to the rootfs mounted by the kernel, thus the
above entry simply re-mounts rootfs as read-write

8. set a root passwd so you can login

{{{
#!bash
passwd
}}}
- or consider adding a user via {{{adduser}}}:
{{{
#!bash
adduser myuser
usermod -a -G tty myuser # add to tty group for tty access
usermod -a -G dialout myuser # add to dialout group for UART access
usermod -a -G sudo myuser # add to sudo group for root access
}}}

9. (optional) configure networking:

- wired ethernet with DHCP on eth0
{{{#!bash
apt-get install net-tools ifupdown
cat <<EOF >> /etc/network/interfaces
allow-hotplug eth0
auto eth0
iface eth0 inet dhcp

EOF
}}}
- or static IP:
{{{#!bash
apt-get install net-tools ifupdown
cat <<EOF >> /etc/network/interfaces
allow-hotplug eth0
auto eth0
iface eth0 inet static
address 192.168.1.1
netmask 255.255.255.0
gateway 192.168.1.254

EOF
}}}
- or wireless (requires ~3MB of additional packages):
{{{
#!bash
apt-get install wpasupplicant iw
cat << EOF >> /etc/network/interfaces
# Wireless interface
auto wlan0
iface wlan0 inet dhcp
wireless_mode managed
wireless_essid any
wpa-driver nl80211
wpa-conf /etc/wpa_supplicant.conf
EOF
wpa_passphrase <myssid> <mypass> >> /etc/wpa_supplicant.conf
}}}

10. (optional) install some useful packages

{{{
#!bash
apt-get install openssh-server # ssh server for remote access
apt-get install can-utils i2c-tools usbutils pciutils # cmdline tools for various
Ventana hardware support
}}}
* Note that by default root ssh access is disabled for security. See
[wiki:/ubuntu#SSHServer this link] for info on enabling it

11. install a kernel and kernel support (kernel+dtbs+modules+firmware+initrd). You

have several options here (see [#kernels above] for more details). Gateworks
recomends using a Gateworks pre-built kernel:
a. **(recommended)** Gateworks Pre-built kernel (includes the same kernel drivers
typically found on Ubuntu kernels including video capture/display and is built by
Gateworks):
{{{
#!bash
cd /
wget http://dev.gateworks.com/ventana/images/linux-ventana.tar.xz
tar -xvf linux-ventana.tar.xz --keep-directory-symlink
depmod $(ls /lib/modules/) # create module dependencies
rm linux-ventana.tar.xz
}}}
* the {{{depmod}}} trick above is to run depmod with the exact kernel version
(which will be the subdir in /lib/modules). An alternative is to run {{{depmod}}}
after the first boot
* this kernel is recommended over the Ubuntu built kernel because it a) enables
some drivers/features that Ubuntu leaves out, such as video capture b) may have
patches for features that are not yet in mainline linux c) enables everything
needed to boot from a Gateworks board static so that you do not need an initrd.
a. Build your own kernel and install it as above with proper bootscript - see
[wiki:linux/kernel#building] for more info (you can do this on a development host
with a cross-toolchain or even even install development tools via the '''build-
essential''' meta-package and build and install sources such as the kernel below
(adds appx 180MB))
a. Ubuntu Pre-built kernel (includes the most kernel drivers and is built by and
supported by Ubuntu):
{{{#!bash
# disable flash-kernel as its not needed and will otherwise error out
echo "FLASH_KERNEL_SKIP=1" >> /etc/environment
export FLASH_KERNEL_SKIP=1 # and export it for current operations
# install kernel/firmware/headers
apt-get install linux-generic
# install mkimage
apt-get install u-boot-tools
# create u-boot image for kernel
mkimage -A arm -O linux -T kernel -C none \
-a 0x10008000 -e 0x10008000 -n "linux" \
-d /boot/vmlinuz-*-generic /boot/uImage
# install device-tree blobs
cp /lib/firmware/*-generic/device-tree/imx6*-gw*.dtb /boot
#blacklist imx rtc driver, Gateworks board uses GSC RTC, and does not use imx RTC
echo "blacklist rtc_snvs" > /etc/modprobe.d/blacklist-rtc.conf
}}}
12. exit the chroot shell and remove files we no longer need
{{{
#!bash
exit
sudo rm $target/usr/bin/qemu-arm-static
}}}
* ''You may wish to move this file else place for later use should you wish to
chroot again.''

13. Now that the rootfs has been created, use one of the following options:

a. Create a tarball of the rootfs

{{{
sudo tar --keep-directory-symlink -cvJf $distro-ventana.tar.xz -C $target .
}}}

b. install to bootable media:

* For a removable block storage device supported by your board such as a USB Mass
Storage device, a microSD, an mSATA SSD the example below will create a single ext4
rootfs partition on a removable block storage device. Ensure you set DEVICE
properly for your system.
{{{
#!bash
DEVICE=/dev/sdc # adjust per your system!
MNT=/mnt # adjust per your system!
# unmount all auto-mounted partitions for this device
sudo umount ${DEVICE}?
# partition disk - single ext partition
printf ",,L,,\n" | sudo sfdisk -uS ${DEVICE}
sync
sudo mkfs.ext4 -O ^64bit -L rootfs ${DEVICE}1
# mount partition
sudo mount ${DEVICE}1 $MNT
# copy the root filesystem
sudo cp -rupv $target/* $MNT/
# unmount the disk
sudo umount ${DEVICE}1
}}}
c. Create a ubifs filesystem image and ubi image for flashing onto raw NAND see
[wiki:linux/ubi#uboot-ubifs]

[=#desktop]
== Hardware Accelerated Desktop UI
While it is not typical to use an embedded system as an Ubuntu desktop we often are
asked how to do it.

With the Ubuntu Focal (20.04) all the software is in place to give you 2D and 3D
hardware acceleration with the IMX6 with a modern kernel such as the Linux 5.4
kernel we use in our pre-built images.

Here are the steps to add a desktop UI:

1. Install gnome desktop:
{{{#!bash
# add packages
apt install gnome-session gnome-terminal
# add a non-root user (required to login)
adduser gateworks
# sync the filesystem and reboot
sync
reboot
}}}
- you'll notice dragging opaque windows around is fairly smooth as it is using
hardware 2D acceleration
- Network manager will not allow access to interfaces in the GUI with "ifupdown"
installed. If you plan to use network functions within the GUI you will need to
remove/purge this package first. All network settings must be configured using the
terminal.
1. 3D opengl hardware acceleration:
{{{#!bash
apt install mesa-utils glmark2
# from gnome-terminal running on display from above:
glxgears # 75fps on IMX6Q displaying HDMI 1080p60hz
glmark2 # another test that renders via opengl
}}}
1. GStreamer Video display
{{{#!bash
apt-get install gstreamer1.0-x gstreamer1.0-tools libgstreamer1.0-0 \
  gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad
gstreamer1.0-plugins-ugly \
  gstreamer1.0-libav gstreamer1.0-alsa gstreamer1.0-gl gstreamer1.0-gtk3
gstreamer1.0-qt5 gstreamer1.0-pulseaudio \
  v4l-utils alsa-utils
# using waylandsink will render 'within' GUI
gst-launch-1.0 videotestsrc ! waylandsink # renders 'within' gui
}}}
- ** Note: ** This pipeline is intended to be run in a terminal within the GUI.
Executing this pipeline as "root" or using the command "sudo" will result in an
error.
- See [wiki:gstreamer gstreamer] wiki page for information on hardware
accelerated encode/decode

[=#kernel]
== Kernel
While a kernel is not specifically part of a root filesystem it usually resides on
the root filesystem. There are several kernel sources you can choose from:
* Gateworks pre-built 5.4 kernel (**recommended**)
* Ubuntu built kernel
* Kernel built by hand

=== Gateworks built kernel

Gateworks periodically updates their pre-built IMX6 kernel release and it is easy
to install on a running system:
{{{#!bash
wget http://dev.gateworks.com/ventana/images/linux-ventana.tar.xz
tar -C / -xvf linux-ventana.tar.xz --keep-directory-symlink
rm linux-ventana.tar.xz
}}}

If you want to clean out old kernels no longer used, you can remove the directory
of modules in /lib/modules/<kernel-version>

Benefits of using the Gateworks kernel:

* contains all drivers 'static' required to boot off boot devices supported by
Gateworks boards (ie NAND, SATA, MMC, USB Mass storage all static in kernel)
removing requirement for an 'inital ramdisk' (initrd) that Ubuntu Built kernels
require
 * contains kernel patches that may not be in mainline yet
* tested and supported by Gateworks

=== Ubuntu built kernel

Ubuntu releases are based on a specific major kernel version. However over time the
Ubuntu team releases new major kernel version updates for specific distro versions.
An {{{apt-get install linux-image}}} will not change the kernel major version and
you have to specifically install a new major version to switch to it.

It is recommended that you use the Gateworks kernel above for the following
reasons:
* Ubuntu built kernels can require initrd for some boot devices complicating
things (ie NAND and USB Mass Storage are kernel modules)
* Ubuntu built kernels may be configured in ways not appropriate for Gateworks
boards (ie the DS1672 RTC driver is not static which complicates restoring system
time on boot from the GSC provided RTC)

If you wish to use an Ubuntu built kernel here are some notes but Gateworks can not
support you if you run into issues as we don't maintain this kernel.

To install a specific kernel image search for available packages and pick the
version you want. For example if wanting the 4-15.0-34-generic kernel:
{{{#!bash
apt-get update
apt-get install linux-image-4.15.0-34-generic
# install mkimage
apt-get install u-boot-tools
# create u-boot image for kernel
mkimage -A arm -O linux -T kernel -C none \
-a 0x10008000 -e 0x10008000 -n "linux" \
-d /boot/vmlinuz-4.15.0-34-generic /boot/uImage
# install device-tree blobs
cp /lib/firmware/4.15.0-34-generic/device-tree/imx6*-gw*.dtb /boot
#blacklist imx rtc driver, Gateworks board uses GSC RTC, and does not use imx RTC
echo "blacklist rtc_snvs" > /etc/modprobe.d/blacklist-rtc.conf
# create u-boot image for initrd
mkimage -A arm -O linux -T ramdisk \
-a 0x0 -e 0x0 -n "initrd" \
-d /boot/initrd.img-4.15.0-34-generic /boot/uramdisk
}}}
- use {{{apt-cache search linux-image}}} to determine what Ubuntu kernel versions
are available

If you want to clean out old kernels no longer used you can use {{{apt list
--installed | grep linux}}} to list installed packages and remove them (remove
linux-headers, linux-image, linux-modules for example). For example if you want to
remove the 4.15.0-42-generic packages:
{{{#!bash
apt purge linux-image-4.15.0-42-generic linux-modules-4.15.0-42-generic linux-
headers-4.15.0-42
}}}
- modify the above to remove the specific version(s) you want to remove

If booting from boot media that requires kernel modules you need to create an
initrd:
* The default Ubuntu kernel supports booting a microSD/SATA rootfs directly, but
lacks nand/ubifs/ubi/usb-storage support. If you need that (and have a large enough
flash to boot from that) you will need to use the Ubuntu initrd:
 - add NAND/ubifs/usb-storage modules to the initrd:
{{{#!bash
cat << EOF >> /etc/initramfs-tools/modules
# for NAND/ubi
gpmi_nand
ubi mtd=2
ubifs

# for usb-storage
ci_hdrc_imx
usb-storage
EOF
update-initramfs -u # press 'Enter' when prompted
# create u-boot image for initrd
mkimage -A arm -O linux -T ramdisk \
-a 0x0 -e 0x0 -n "initrd" \
-d /boot/initrd.img-*-generic /boot/uramdisk
}}}

You will need to create a boot script that sets kernel cmdline properly based on
boot device and loads the Ubuntu initrd if needed. You can do this on the target
board:
{{{#!bash
# The Gateworks bootscript is a good starting point
wget https://raw.githubusercontent.com/Gateworks/linux-
imx6/gateworks_5.4.45/gwventana_bootscript -O /boot/6x_bootscript-ventana.txt
# re-enable ramdisk when its needed
sed -i 's/^setenv rd_addr$/#setenv rd_addr/' /boot/6x_bootscript-ventana.txt
mkimage -A arm -O linux -T script -n bootscript -d /boot/6x_bootscript-
ventana.txt /boot/6x_bootscript-ventana
}}}