buildroot-external-ad
=====================

Buildroot external overlay for Avionic Design Meerkat-based systems. Contains
support for building a root-filesystem including Linux4Tegra binary driver
support.

The officially supported buildroot version is currently 2016.05.  Both
older and younger releases won't work - due to repeated and ongoing
merges of packages from our buildroot external into upstream buildroot,
older buildroot releases are missing packages that have meanwhile been
removed from this external, while newer buildroot releases will
duplicate packages that are still in this external.

Configuring Meerkat baseboard support
=====================================

Root filesystem (rootfs) images built by this package support multiple
Avionic Design Meerkat baseboards by including the corresponding
device-tree files in the /boot directory.  Instructions on how to change
the list of included device-trees are below.

While the rootfs provides the device-tree files, the choice which
device-tree is being used for booting Linux is left to the bootloader,
u-boot.  This allows using a single, unmodified rootfs on different
target baseboards.  It also means that in order to boot Linux with full
support for a specific target baseboard, the u-boot on that device need
be configured for that board.

Configuring device-tree selection in u-boot for a specific baseboard can
be achieved by either modifying the u-boot environment, or editing the
file /boot/extlinux/extlinux.conf in the rootfs.

To modify the u-boot environment to choose the correct device-tree for a
baseboard "foo", connect to the target with serial console, interrupt
the boot sequence by pressing any key, and then change the "board"
environment variable:

  setenv board foo
  saveenv

This will persist rootfs changes, and keep the rootfs generic.

If you are choosing to build u-boot from within buildroot using this
buildroot external, this setting can be pre-configured for the u-boot
image by adjusting the buildroot menuconfig item "User provided options
/ cbootimage-configs / u-boot flasher bootcmd extras"
(BR2_PACKAGE_CBOOTIMAGE_CONFIGS_FLASHER_EXTRA_BOOTCMD) to execute the
setenv command above.

Alternatively, you can edit /boot/extlinux/extlinux.conf on the rootfs
and replace the line with the "fdtdir" keyword with

  fdt /boot/tegra124-foo.dtb

This method ties the rootfs to a specific carrier board model. It also
overrides the first method.

Both, changing the u-boot environment or changing extlinux.conf on the
rootfs, will make u-boot boot Linux with the device-tree file
tegra124-foo.dtb.

Quickstart the build
====================

Prerequistes: You must install the buildroot requirements as described in the
buildroot manual:
http://buildroot.uclibc.org/downloads/manual/manual.html#requirement

0. Create working-directory

# mkdir -p ~/dev/meerkat
# export WORKING_DIR=~/dev/meerkat

1. Grab buildroot and our overlay

# cd ${WORKING_DIR}
# git clone https://github.com/avionic-design/buildroot-external-ad.git
# git clone git://git.buildroot.net/buildroot
# cd ${WORKING_DIR}/buildroot
# git checkout -b 2016.05 2016.05

2. Prepare build

The following commands describe an out-of-tree build, where the O=...
make argument points to a subdirectory build/meerkat-rootfs in the
buildroot top-level directory.

# cd ${WORKING_DIR}/buildroot
# make BR2_EXTERNAL=../buildroot-external-ad O=build/meerkat-rootfs meerkat-l4t_defconfig

For a rootfs that includes the enlightenment window manager and extra
GUI packages, change the line above to

# make BR2_EXTERNAL=../buildroot-external-ad O=build/meerkat-rootfs meerkat-l4t-bsp_defconfig

In order to configure the Linux kernel for the baseboard, select the
corresponding devicetree:

# make O=build/meerkat-rootfs menuconfig

Select sub-menu "Kernel", item "Device Tree Source file names".  Here,
enter the baseboard devicetree filename as found in the kernel sources
provided by Avionic Design, for example "tegra124-kein-baseboard" or
"tegra124-tobor".  Exit menuconfig, saving the configuration.

3. Start build

If you want to have the cross-compilation toolchain pre-built without
building the root filesystem and kernel, execute:

# make O=build/meerkat-rootfs toolchain

Build the root filesystem and the kernel:

# make O=build/meerkat-rootfs

This generates a kernel zImage, devicetree blob, uImage, and rootfs.

For example, if you are building for the "kein-baseboard" baseboard, the
following output files are generated:
# ls -1F build/meerkat-rootfs/images/
# rootfs.ext2
# rootfs.ext4@
# tegra124-kein-baseboard.dtb
# uImage-tegra124-kein-baseboard
# zImage*

The format of the rootfs depends on the buildroot configuration and can
be either a tarball (rootfs.tar) or a filesystem image (e.g.
rootfs.ext4).  Filenames will also vary depending on the baseboard
chosen in step 2.

uImage-tegra124-kein-baseboard can be loaded by u-boot to boot the kernel.
rootfs.tar or rootfs.ext4 contains a root filesystem including Xorg and
nvidia L4T drivers.

Note that the initial build will pull the latest kernel by Avionic
Design from github, while later builds will automatically re-use a
cached tarball of that kernel.  In order to pull an updated kernel from
github, remove both the cached tarball and the linux kernel build
directory before triggering a rebuild:

# rm dl/linux-meerkat_l4t-*.tar.gz
# rm -rf build/meerkat-rootfs/build/linux-meerkat_l4t-*
# make linux

4. Flash the rootfs onto the eMMC

In order to flash the root filesystem onto the eMMC on the Meerkat COM,
you can leverage USB mass storage support (aka UMS) in u-boot, which
lets you write to the eMMC as a standard block device on the host.
Current u-boot builds from Avionic Design automatically drop into UMS
mode if no bootable OS is found.  Otherwise, UMS in u-boot can still be
started manually.  To do this, connect to the serial console and power
up or reset the board.  Interrupt the boot sequence in u-boot by hitting
any key, which drops into the u-boot shell. Then, enter:

# run bootcmd_ums0

This turns the eMMC into a standard USB mass storage block device (with
ID 0955:701a) that can be accessed via the recovery USB port.  The BSP
comes with a helper script board/meerkat-l4t/flash.sh which, provided
with the filename of a rootfs image, automatically identifies the K1 USB
mass storage device on the host, creates a single partition on it,
and writes the filesystem image:

# ../buildroot-external-ad/board/meerkat-l4t/flash.sh \
	build/meerkat-rootfs/images/rootfs.ext4

When the process has completed, exit UMS in u-boot by hitting Ctrl-C.
The system is now ready to boot from the eMMC.

If there are existing partitions on the eMMC and you are running a
desktop system that auto-mounts them, the script flash.sh will fail and
complain about partitions on the device being used.  If the device is
e.g. /dev/sdb, umount any partitions /dev/sdb* (with *=1,2,...) and
repeat.  Note that using the "eject" feature of your desktop environment
may power down the USB port the board is connected to; better umount on
the command line instead.

5. Default password for root and the default user

The two buildroot configurations meerkat-l4t_defconfig and
meerkat-l4t-bsp_defconfig install passwords for root and the default
user.

Use "password" to login.