[[PageOutline]]

= Ubuntu on Newport =
This page is dedicated details regarding running Ubuntu on an Gateworks Newport Board.

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]  

See also:
 * [wiki:ubuntu Gateworks Ubuntu page]


[=#prebuilt]
== Gateworks pre-built Ubuntu Disk Image ==
Gateworks provides a pre-built Ubuntu firmware images for the Newport Family:
 * [https://github.com/Gateworks/linux-newport/releases/download/v4.14.4-00005-g9e5958b/linux-newport.tar.xz linux-newport.tar.xz] - Compressed TAR archive of pre-built Linux kernel
 * [http://dev.gateworks.com/newport/ubuntu/xenial/20171215/xenial-newport.tar.xz xenial-newport.tar.gz] - Compressed TAR archive of Ubuntu 16.04 Xenial arm64 root filesystem (does not include kernel) ([http://dev.gateworks.com/newport/ubuntu/xenial/20171215/xenial-newport.manifest package manifest])
 * [https://github.com/Gateworks/images-newport/releases/download/v0.1.0/xenial-newport.img.gz xenial-newport.img.gz] - Compressed Disk Image containing Firmware, Linux kernel, and Ubuntu 16.04 Xenial root filesystem. To update the firmware using this see [wiki:newport#serial-ethernet here]

Features:
- Ubuntu 16.04 aarch64 core (from debootstrap instructions)
- Gateworks Newport Linux kernel (Linux 4.14 based)
- several pre-installed packages
- eth0 dhcp
- user root passwd root

To install the kernel and root filesystem on a removable block storage device see [#disk-images below].


[=#disk-images]
== Disk Images ==
Gateworks releases disk images that can be easily flashed using the U-Boot Bootloader (see [wiki:newport#serial-ethernet here]). These disk images contain a partition table so they are tailored to the specific eMMC device on the boards they are intended for. Additionally they are configured for a small partition size to keep flash programming time at a minimum. This requires resizing the rootfs partition be resized in order to take advantage of the remaining flash space.

The script used to create these images can be found on !GitHub [https://github.com/Gateworks/images-newport/raw/master/mkimage here] and an example usage is:
{{{#!bash
sudo ./mkimage xenial-newport 7264 1536 firmware-newport.img xenial-newport.tar.xz linux-newport.tar.xz
}}}
 * The user partition of the 8GiB eMMC used on Newport is 7264MB
 * We need around 1536MB of partition space for the extracted kernel and root filesystem

To flash this compressed disk image to a board see [wiki:newport#serial-ethernet here]

To install the kernel and root filesystem on a removable block storage device see [wiki:linux/blockdev].


[=#debootstrap]
== Root filesystem ==
A popular way to create an 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.

Requirements:
- Linux Ubuntu or Debian System with network connection and sudo permissions

Important notes:
 * 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.

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

2. Perform first stage install of minimal filesystem for {{{arm64}}} architecture:
{{{
#!bash
target=rootfs
distro=xenial
sudo debootstrap --arch=arm64 --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-aarch64-static $target/usr/bin
}}}
 * See http://ports.ubuntu.com/ubuntu-ports/dists/ for a list of current Ubuntu releases: 16.10=yakkety (latest), 16.04=xenial (latest LTS), 15.04=vivid, 14.10=utopic (LTS), 14.04=trusty (LTS), 12.04=precise (LTS), 10.04=lucid (LTS).
 * this minimal rootfs can be considered about the same as an Ubuntu-core downloaded rootfs however it 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=xenial
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}-$(uname -m) > /etc/hostname
}}}

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

8. (optional) configure networking:
 - wired ethernet with DHCP on eth0
{{{
#!bash
cat <<EOF >> /etc/network/interfaces
allow-hotplug eth0
auto eth0
iface eth0 inet dhcp

EOF
}}}
 - or static IP:
{{{
#!bash
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
}}}

9. (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 hardware support
}}}
 * Note that by default root ssh access is disabled for security. See [#ssh below] for info on enabling it

10. install Gateworks pre-built kernel:
{{{#!bash
apt-get install wget
cd /
wget http://svn.gateworks.com/newport/images/gateworks-linux-arm64-4.14.tar.bz2
tar -xvf gateworks-linux-arm64-4.14.tar.bz2
}}}

11. exit the chroot shell and remove files we no longer need
{{{
#!bash
exit
sudo rm $target/usr/bin/qemu-arm-static
}}}

12. 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. We use the 'udisks' application for mount/unmount so that the mount-point is obvious - if you know what your doing you could use standard mount/unmount as well:
{{{
#!bash
DEVICE=/dev/sdc
# 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 -L rootfs ${DEVICE}1
# mount partition (will mount to /media/rootfs/)
sudo udisks --mount ${DEVICE}1
# copy the root filesystem
sudo cp -rupv $target/*  /media/rootfs/
# unmount the disk
sudo udisks --unmount ${DEVICE}1
}}}