VAR-SOM-AM33 Yocto FIDO GS

VAR-SOM-AM33 Yocto 1.8 (Fido) Distribution User's Guide

About this Manual

This document describes how to install Variscite's Yocto release for the VAR-SOM-AM33.

The Yocto distribution provides a fundamental software platform for development, deployment and execution on VAR-SOM-AM33. It abstracts the functionality provided by the hardware.

In this context, the document contains instructions to:

• Install the release on a development machine.
• Build the sources included in this release.
• Instaling the binaries on the VAR-SOM-AM33.
• Booting the VAR-SOM-AM33.

Installation

Prerequisites

Before starting the installation, make sure below system requirements are met:

• Host machine running a Ubuntu 14.04 64 LTS.
• VAR-SOM-AM33 Evaluation Kit + VAR-SOM-AM33 Yocto support installation sources and binaries (from FTP). Please refer to support@variscite.com for obtaining FTP credentials.

The Linux host is used for the following:

• Recompiling U-Boot / kernel.
• Hosting the NFS server to boot the EVM with NFS as root filesystem.

Either of Windows or Linux host can be used for:

• Hosting the TFTP server required for downloading the kernel and file-system images from U-Boot using Ethernet.
• Running a serial console terminal application

Building the Yocto distribution via Bitbake will produce a complete set of downloaded source code + binaries for each component:

• Yocto build environment
• Downloaded Linux kernel source code + build kernel binaries (DTB and zImage) for VAR-SOM-AM33.
• Downloaded U-Boot source code + build U-boot binaries (MLO and U-boot) for VAR-SOM-AM33.
• Linux root file-system.

Install the Arago toolchain

$ wget --no-check-certificate http://releases.linaro.org/15.05/components/toolchain/binaries/arm-linux-gnueabihf/gcc-linaro-4.9-2015.05-x86_64_arm-linux-gnueabihf.tar.xz
$ sudo tar -xvf gcc-linaro-4.9-2015.05-x86_64_arm-linux-gnueabihf.tar.xz -C /opt

Install development tools

$ sudo apt-get install git build-essential diffstat texinfo gawk chrpath gcc-multilib wget socat libsdl1.2-dev mtd-utils dos2unix

Download the Yocto Distribution

To quickly start making your own builds using meta-ti BSP layer and meta-arago Distribution layer, you can follow this short Quick Start section by entering below commands. For more expanded guide with each step detailed and sample output of the entered commands shown, please see the next Detailed Setup section.

$ mkdir ~/yocto_varsomam33
$ cd ~/yocto_varsomam33
$ git clone git://arago-project.org/git/projects/oe-layersetup.git tisdk

Downloading VAR-SOM-AM33 Support

Download the VAR-SOM-AM33 Yocto support installation from github:

$ mkdir ~/yocto_varsomam33/tisdk/sources
$ cd ~/yocto_varsomam33/tisdk/sources
$ git clone https://github.com/varigit/meta-variscite-amx3

Downloading the YOCTO Fido 1.8 configuration

Download the YOCTO Fido 1.8 configuration as follows:

$ cd ~/yocto_varsomam33/tisdk
$ ./oe-layertool-setup.sh -f sources/meta-variscite-amx3/conf/var-som-amx3_sdk-02.00.00-config.txt
$ cd build
$ . conf/setenv

At this point, Variscite Yocto support has been installed over the Yocto distribution and ready to be be built.

local.conf customizations

Edit you local.conf file:

$ cd ~/yocto_varsomam33/tisdk/build
$ gedit conf/local.conf 

Change your parallel build and download directory:

Parallel build

Set the build parameters to fully utilize your host machine BB_NUMBER_THREADS = '4'
PARALLEL_MAKE = '-j 6' BB_NUMBER_THREADS should be your host machine's number of threads minus 2 or same. PARALLEL_MAKE should be the number of threads your host machine has plus two.

Download directory

Recommended to save download time and space. DL_DIR = "/home/<uname>/yocto_dl"

Setting up the Toolchain

$ export PATH=/opt/gcc-linaro-4.9-2015.05-x86_64_arm-linux-gnueabihf/bin:$PATH

Building the VAR-SOM-AM33 Yocto image

First, change directory to the build directory of Yocto:

$ cd ~/yocto_varsomam33/tisdk/build

The developer can build the tisdk-rootfs-image image as follows:

$ export PATH=/opt/gcc-linaro-4.9-2015.05-x86_64_arm-linux-gnueabihf/bin:$PATH
$ . conf/setenv
$ MACHINE=varsomam33 bitbake tisdk-rootfs-image

After the image was built, all images will be located in: ~/yocto_varsomam33/tisdk/build/arago-tmp-external-linaro-toolchain/deploy/images/ - Specifically:

• MLO image
• u-boot.img image
• zImage
• zImage-var-som-am33.dtb
• Compressed rootfs image: tisdk-rootfs-image-varsomam33.tar.bz2

If the rootfs directory already exists - Please make sure to erase all its content before extracting a new rootfs image into it:

$ sudo rm -rf ~/yocto_varsomam33/rootfs/*

Extract the rootfs as follows:

 $ sudo mkdir ~/yocto_varsomam33/rootfs
 $ sudo tar xvf ./arago-tmp-external-linaro-toolchain/deploy/images/varsomam33/tisdk-rootfs-image-varsomam33.tar.gz -C ~/yocto_varsomam33/rootfs

This creates a rootfs directory for the Yocto / VAR-SOM-AM33 build.

Linux Root File-System

To boot-up Linux, a target file-system is needed. A file-systems is built from the Yocto distribution for VAR-SOM-AM33.

• Demo filesystem (~250MB) - This file system is created by taking the base file system and adding all the additional SDK components such as 3D graphics, matrix, profiling tools, etc..

Create a bootable SD-Card

To create a bootable SD-Card image, which includes a UBIFS file-system based recovery image - Please do as follows:

• Insert a 4GB SD-Card to host computer
• Run dmesg command to identify which /dev/sdX was created

• To generate the SD-Card - Run script (and choose the correct /dev/sdX of the 4GB SD-Card inserted):

$ cd ~/yocto_varsomam33/tisdk/sources/meta-variscite-amx3/utils
$ sudo ./create-sdcard.sh ~/yocto_varsomam33/tisdk ~/yocto_varsomam33/rootfs/

The above procedure will result in a bootable SD-Card including MLO, U-boot, Kernel and file system + Linux recovery image to flash the NAND based on UBI file-system. To boot the bootable SD-Card, follow the steps below:

• Insert the SD card into the SD/MMC slot of the custom board
• Press and hold the boot select switch while powering ON the board
• Login as root (no password)

Boot

The Kernel and root the file-system can be booted either from NAND, SD-Card or can be retrieved via ethernet to RAM using TFTP.

Nand Flash root file-system is UBIFS based which is the most recommended filesystem for nand flashes.

Following sections describe various kernel boot options possible.

Boot from MMC/SD

For creating a bootable SD , follow the below instruction on creating a resude SD. http://www.variwiki.com/index.php?title=VAR-SOM-AM33_Arago_GS#NAND_Recovery

To boot the Linux, type:

U-Boot# run mmc_boot

Boot from NAND

By default the VAR-SOM-AM33 boots from NAND.

The SPL, U-Boot, kernel uImage and UBIFS filesystem are flashed on the NAND flash at production.

Flash Images to NAND

Replacing Nand Flash images can be done from either Linux user space or U-Boot.

From U-Boot

U-Boot # mmc rescan
U-Boot # nand erase 0x0 0x280000
U-Boot # mmc rescan
U-Boot # fatload mmc ${mmc_dev} ${loadaddr} MLO
U-Boot # nand write ${loadaddr} 0x0 0x20000
U-Boot # nand write ${loadaddr} 0x20000 0x20000
U-Boot # nand write ${loadaddr} 0x40000 0x20000
U-Boot # fatload mmc ${mmc_dev} ${loadaddr} u-boot.img
U-Boot # nand write ${loadaddr} 0x80000 0x1c0000
U-Boot # fatload mmc ${mmc_dev} ${loadaddr} uImage
U-Boot # nand erase 0x280000 0x500000
U-Boot # nand write ${loadaddr} 0x280000 0x500000

From Linux shell

  << Install SPL >>
$ flash_erase /dev/mtd0 0 0
$ flash_erase /dev/mtd1 0 0
$ flash_erase /dev/mtd2 0 0
$ flash_erase /dev/mtd3 0 0
$ nandwrite -p /dev/mtd0 <MLO file>
$ nandwrite -p /dev/mtd1 <MLO file>
$ nandwrite -p /dev/mtd2 <MLO file>
$ nandwrite -p /dev/mtd3 <MLO file>

  << Install U-Boot >>
$ flash_erase /dev/mtd4 0 0
$ flash_erase /dev/mtd5 0 0
$ nandwrite -p /dev/mtd4 <u-boot.img file>

  << Install Kernel >>
$ flash_erase /dev/mtd6 0 0
$ nandwrite -p /dev/mtd6 <uImage file>

Boot over Network (Ethernet)

NOTE:
When setting a MAC address please ensure that the LS-bit of the 1st byte is not 1 i.e. when setting the MAC address: y in xy:ab:cd:ef:gh:jk has to be an even number.

            For more info this refer to the wiki page http://en.wikipedia.org/wiki/MAC_address.

When kernel image and root file-system are fetched from a TFTP/NFS server:

• Ensure that the SOM is connected to network with DHCP and TFTP server set up
• If the TFTP server supports negotiation between client and server, Disable it
• Copy 'uImage' kernel image to TFTP server's root directory.
• Set 'ethaddr' U-Boot environment variable with proper ethernet address in format 'xx:xx:xx:xx:xx:xx' (replace 'xx' with proper hexadecimal values)
  
• Setup NFS server and export one of the provided pre-build root file-system
• Execute following commands at U-Boot prompt. Assuming kernel image name as 'uImage':
  

U-Boot # setenv fdtfile '<var-som-am33.dtb filename on TFTP>'
U-Boot # setenv bootfile <zImage filename on TFTP>
U-Boot # setenv netargs 'setenv bootargs console=${console} ${optargs} root=/dev/nfs nfsroot=${serverip}:${rootpath},${nfsopts} rw ip=dhcp vram=50M'
U-Boot # setenv serverip <Server IP address>
U-Boot # setenv rootpath '<Path of the exported root file-system on the NFS server>'
U-Boot # run netboot

Note, that the roopath parameter should be the directory of the extracted rootfs image, as explained above in section Building the VAR-SOM-AM33 Yocto image extracting the image to '/home/user/yocto_varsomam33/rootfs/'.

NAND Recovery

As an easy and fast way to recover the VAR-SOM-AM33 NAND flash, Variscite provides a recovery SD card image that can be used to install the pre-built Linux and Android systems.
This SD card image includes a script (nand-recovery.sh) that installs all the boot images and root file-system.

Preparing rescue SD-Card

• Plug your SD card to your Linux machine, run dmesg and see what device is added (i.e. /dev/sdX)
• xz -d am33-som-nand-recovery-sd_Yocto_1_6_v1.img.xz
• dd if=am33-som-nand-recovery-sd_Yocto_1_6_v1.img of=/dev/sdX bs=128k
• sync

Recover Nand Flash: TI-SDK (Linux with TI Matrix)

• Insert the SD-card into the SD/MMC slot of the custom board
• Press and hold the boot select switch while powering ON the board
  
• Login as root (no password)
• From Linux command line, type: "nand-recovery.sh -o TISDK". (This will install Linux on the NAND)
• Unplug the SD card and reboot

Recover Nand Flash: Android

• Insert the SD-card into the SD/MMC slot of the custom board
• Press and hold the boot select switch while powering ON the board
  
• Login as root (no password)
• From Linux command line, type: "android-nand.sh". (This will install Android on the NAND)
• Unplug the SD card and reboot

Build U-Boot out of yocto tree

Please refer to : Build u-boot out of yocto tree

Linux Kernel

Build linux kernel out of yocto tree

For manually building the Linux kernel, out of the yocto build system, please refer to :
Build linux kernel out of yocto tree

Installing the Kernel

Once the Linux kernel and modules have been compiled they must be installed. In the case of the kernel image this can be installed by copying the uImage file to the location for downloading using TFTP, or put in an SD-card.

For example: when using TFTP boot,  /tftpboot directory is the common location, whereas when booting from SD card, file should be put in the first FAT partition.

To install the kernel modules, provide the rootfs location, see below.

If the rootfs directory already exists - Please make sure to erase all its content before extracting a new rootfs image into it:

$ sudo rm -rf ~/yocto_varsomam33/rootfs/*

First, extract the rootfs of the tisdk-rootfs-image image as follows:

 $ sudo mkdir ~/yocto_varsomam33/rootfs
 $ sudo tar xvf ./arago-tmp-external-linaro-toolchain/deploy/images/varsomam33/tisdk-rootfs-image-varsomam33.tar.gz -C ../../rootfs

This command will create a directory tree in that location: lib/modules/<kernel version> which will contain the dynamic modules corresponding to this version of the kernel. The base location should usually be the root of your target file system. The general format of the command is:

$ sudo make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- modules_install INSTALL_MOD_PATH=<path to root of file system> 

For example if you are installing the modules to an NFS share located at ~/yocto_varsomam33/rootfs you would do:

$ sudo make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- modules_install INSTALL_MOD_PATH=~/yocto_varsomam33/rootfs

Installing the kernel to a VAR-SOM-AM33 SD-Card

In order to install the kernel to the SD-Card, please follow the instructions below:
1) Insert SD-Card with VAR-SOM-AM33 image.
2) Build the kernel as explained above.
3) Install by executing the following commands:

$ sudo cp -a arch/arm/boot/zImage /media/rootfs/boot
$ sudo cp -a arch/arm/boot/dts/var-som-am33.dtb /media/rootfs/boot
$ sudo make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- modules_install INSTALL_MOD_PATH=/media/rootfs 
$ sync
$ sudo umount /media/boot
$ sudo umount /media/rootfs
$ sudo umount /media/user

Out-of-tree Kernel Modules

NOTE:
Some drivers like the SGX and WLAN drivers are delivered as modules outside of the kernel tree. These drivers binaries are already included in the pre-built root file-systems provided by Variscite.

Support carrier boards without a Touch screen

In order to skip the Touch screen calibration on the first boot on carrier boards without a Touch screen -

Please insert the SD-Card to a Linux machine (or VM) after creating the SD-Card and type the following command to disable touch screen calibration at the first boot:

$ sudo touch /media/boot/ws-calibrate.rules