VAR-SOM-AM33 Yocto GS

VAR-SOM-AM33 LSP User's Guide

About this Manual

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

The Yocto package 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 of the package, make sure below system requirements are met:

• Host machine running a version of Windows OS such as Windows XP / 7 or a Linux such as Ubuntu.
• [T.B.D] - VAR-SOM-AM33 Evaluation Kit + sources and binaries. 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

== Install Yocto packages

Variscite Yocto release consists of :

• Yocto build environment
• Linux kernel source code
• U-Boot source code
• Linux root file-system binaries examples.

Please follow the instructions on http://arago-project.org/wiki/index.php/Setting_Up_Build_Environment to setup the required Host tools, download TI's Arago Yocto package to the Host Ubuntu machine.

Extract Variscite Yocto installation package as follows:

$ mkdir yocto_variscite_package_v1_0_installation
$ tar -xjf yocto_variscite_package_v1_0_installation.tar.bz2 -C ~/yocto_variscite_package_v1_0_installation

Once the Arago Yocto package is installed on the Host Ubuntu machine, please extract the Variscite package tar.gz and apply the patches as follows:

$ mkdir yocto_varsomamxx
$ cd ~/yocto_varsomamxx/tisdk
$ ~/yocto_variscite_package_v1_0_installation/variscite_utils/install_variscite_arago_var-som-am33.sh ~/yocto_variscite_package_v1_0_installation ~/yocto_varsomamxx/tisdk

At this point, the Variscite Yocto package has been installed over the Yocto package and can be built.

The developer can build either core-image-sato-var SW package or tisdk-rootfs-image package, as follows:

$ MACHINE=am335x-evm bitbake core-image-sato-var

or

$ MACHINE=am335x-evm bitbake tisdk-rootfs-image

After the image was built, extract the rootfs as follows:

$ mkdir ~/yocto_varsomamxx/rootfs
$ sudo tar xvf ./arago-tmp-external-linaro-toolchain/deploy/images/core-image-sato-var-varsomam33.tar.bz2 -C ~/yocto_varsomamxx/rootfs

This creates a directory VAR-AM335x-LSP with the following contents:

\---SDK-06.00.00.00.VAR.R13
+----linux-3.2.0-sdk06.00.00.00.var_r13/
|    +----linux source code ...
|    +----var-som-am33-patches/
+----u-boot-sdk06.00.00.00.var_r13/
|    +----uboot source code ...;
|    +----var-som-am33-patches/
+----binary-sdk06.00.00.00.var_r13/
|    |----base-rootfs-var-som-am33.tar.bz2
|    |----rootfs-var-som-am33.tar.bz2
|    |----boot/
|    |    |----MLO-var-som-am33
|    |    |----u-boot-var-som-am33.img
|    |    |----uImage-var-som-am33
|    |----ubi/
|    |    |----base-rootfs-var-som-am33.ubi.img
|    |    |----rootfs-var-som-am33.ubi.img

U-Boot Source Code

• U-Boot sources directory is at u-boot-sdk06.00.00.00.var_r13
• The directory u-boot-sdk06.00.00.00.var_r13/var-som-am33-patches includes Variscite's patches (already applied) to support the VAR-SOM-AM33.
• Based on the open source repositorie: https://git.ti.com/ti-u-boot/ti-u-boot/trees/ti-u-boot-2013.01.01-amsdk-06.00.00.00, commit: 540aa6fbb0c9274bda598f7e8819ed28259cad6b.

Linux Kernel Source Code

• Linux kernel source s directory is at linux-3.2.0-sdk06.00.00.00.var_r13
  
• The directory linux-3.2.0-sdk06.00.00.00.var_r13/var-som-am33-patches includes Variscite's patches(already applied) to support the VAR-SOM-AM33.
• Based on the open source repositorie: http://arago-project.org/git/projects/?p=linux-am33x.git;a=shortlog;h=refs/heads/v3.2-staging, commit: d5720d33bc7c434f9a023dbb62c795538f976b7a

Linux Root File-System

To boot-up Linux, a target file-system is needed. Two Arago based file-systems are included in the LSP binaries package.

Base filesystem (~11MB) - It has some basic utilities installed but is intended to be rather small and light weight.

Demo filesystem (~170MB) - 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...

Further explanation about customizing these file-systems can be found here.

Toolchain

GNU toolchain for ARM processors from Linaro is recommended. Linaro Toolchain 2013.03 (GCC 4.7) can be found here. 

Environment Setup

After installing the toolchain, the environment in the Linux host needs to be setup.

Set the environment variable PATH to contain the binaries of the Linaro cross-compiler tool-chain.

For example, in bash: 

$ export PATH=/opt/toolchain/gcc-linaro-arm-linux-gnueabihf-4.7-2013.03-20130313_linux/bin:$PATH

Add the location of U-Boot tools directory to the PATH environment variable (required for mkimage utility that is built as part of U-Boot build process and is needed to generate uImage when building the kernel)

For example, in bash: 

$ export PATH=/opt/u-boot/tools:$PATH

NOTE: Actual commands to be used for setting the environment variables will depend upon the shell and location of the tools.

NOTE:
To help get started quickly, the LSP package comes with pre-built binaries. However, after making any changes to U-Boot and/or Linux Kernel, they have to be cross-compiled and the new binaries that are generated should be used.

U-Boot

In AM335x the ROM code serves as the 1st stage bootloader. The 2nd and the 3rd stage bootloaders are based on U-Boot.

The binary for the 2nd stage is referred to as SPL and the binary for the 3rd stage as simply U-Boot. SPL is a non-interactive loader and is a specially built version of U-Boot. It is built concurrently when building U-Boot.

The ROM code can load the SPL image from the NAND or SDMMC devices.

Building U-Boot

Change to the base of the U-Boot directory.

$ cd SDK-06.00.00.00.VAR.R13/u-boot-sdk06.00.00.00.var_r13

info

Build

$ [ -d ./var_am335x ] && rm -rf ./var_am335x
$ make O=var_am335x CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm var_am335x_config
$ make O=var_am335x CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm 

This will generate two binaries in the var_am335x directory, MLO and u-boot.img along with other intermediate binaries that may be needed in some cases.

For information on installing the kernel into NAND on the SOM please see the Installing the Linux Kernel section.

U-Boot Environment Settings

The VAR-SOM-AM33 U-Boot has default environmant settings that allows boot from NAND, SD/MMC card and Ethernet.

By default the boot device is NAND, for more information about boot options go to Boot section.

Linux Kernel

Cleaning the Kernel Sources

Prior to compiling the Linux kernel make sure that the kernel sources are clean.

Enter linux kernel directory:

$ cd SDK-06.00.00.00.VAR.R13/linux-3.2.0-sdk06.00.00.00.var_r13

NOTE:
The next step will delete any saved .config file in the kernel tree as well as the generated object files. If you have done a previous configuration and do not wish to lose your configuration file you should save a copy of the configuration file before proceeding.

The command to clean the kernel is:

$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- mrproper

Configuring the Kernel

Before compiling the Linux kernel it needs to be configured to select which components will become part of the kernel image:

Using Default Configurations

To build the defualt configuration for the VAR-SOM-AM33:

$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- var_am335x_defconfig

Customizing the Configuration

For configuring the kernel run:

$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- menuconfig

Once the configuration window is open you can select which kernel components will be included in the build. Exiting the configuration will save your selections to a file in the root of the kernel tree called .config.

Compiling the Kernel

Once the kernel has been configured compile kernel:

$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- uImage

This will result in a kernel image file being created in the arch/arm/boot/ directory called uImage. This file can be used by u-boot to boot your device.

If you selected any components of the kernel to be build as dynamic modules you must issue an additional command to compile those modules. The command is:

$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- modules

This will result in .ko (kernel object) files being placed in the kernel tree. These .ko files are the dynamic kernel modules. The next section will cover how to install these modules.

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 shoudl be put in the first FAT partition.

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

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:

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

For example if you are installing the modules to an NFS share located at /home/user/targetNFS you would do:

$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- INSTALL_MOD_PATH=/home/user/targetNFS modules_install

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-build root file-systems provided by Variscite.

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 serverip <Server IP address>
U-Boot # setenv rootpath <Path of the exported root file-system on the NFS server>
U-Boot # run net_boot

UBIFS

UBIFS is used for Linux root file-system on the VAR-SOM-AM33 NAND Flash.

{{note|NOTE:
Pre-built UBI root file-system binaries are provided by Variscite as part of the LSP binaries package. |info}

Compilling UBIFS Tools

The MTD and UBI user-space tools are available from the the following git repository:

$ git clone git://git.infradead.org/mtd-utils.git
$ cd mtd-utils/
$ git checkout v1.5.0
$ make

IMPORTANT

Tested wuth mtd-utils version is 1.5.0.

For instructions on compiling MTD-utils, refer MTD-Utils Compilation.

Creating UBIFS

This section describes steps for creating a UBI rootfs image to be flashed to the VAR-SOM-AM33 NAND Flash.

• mkfs.ubifs

$ sudo mkfs.ubifs/mkfs.ubifs -r rootFS/ -F -o system_ubifs.img -m 2048 -e 126976 -c 1960

Where:

-m 2KiB (or 2048)

The minimum I/O size of the underlying UBI and MTD devices. In our case, we are running the flash with no sub-page writes, so this is a 2KiB page.

-e 124KiB (or 126976)

Erase Block Size: UBI requires 2 minimum I/O units out of each Physical Erase Block (PEB) for overhead: 1 for maintaining erase count information, and 1 for maintaining the Volume ID information. The PEB size for our flash is 128KiB, so this leads to each Logical Erase Block (LEB) having 124KiB available for data.

-c 1960

The maximum size, in LEBs, of our file system.

-r rootFS

Use the contents of the 'rootFS/' directory to generate the initial file system image.

-F

File-system free space has to be fixed up on first mount (http://www.linux-mtd.infradead.org/faq/ubifs.html#L_free_space_fixup)

-o system_ubifs.img

Output file.

NOTE: On AM335x, -F option is required when creating ubifs image. If this option is not used, Kernel may crash while loading the Filesystem from UBI partition.

The output of the above command, 'system_ubifs.img' is fed into the '<b>ubinize'</b> program to wrap it into a UBI image. 
The images produced by mkfs.ubifs are later used by the ubinize tool to create a UBI image is flashed to the raw flash to be used a UBI partition. 

• Create ubinize.cfg file and write the bellow contents into it:
  

[rootfs]
mode=ubi
image=system_ubifs.img
vol_id=0
vol_size=220MiB
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize

• ubinize

$ ubi-utils/ubinize -o rootfs-var-som-am33.ubi.img -m 2048 -p 128KiB -s 2048 -O 2048 ubinize.cfg

Where:

-o rootfs-var-som-am33.ubi.img

Output file.

-m 2KiB (or 2048)

Minimum flash I/O size of 2KiB page.

-p 128KiB

Size of the physical eraseblock of the flash this UBI image is created for

-O 2048

offset if the VID header from start of the physical eraseblock

The output of the above command, 'rootfs-var-som-am33.ubi.img' is the required image.

Using UBIFS

We can Flash UBIFS image from either Linux Kernel or U-Boot.

From U-boot

Get the UBIFS image to U-Boot from tftp or MMC/SD.

Since we copy the data to NAND, Empty/Erase the required RAM. Then, g et the UBIFS image to U-Boot

U-Boot # mw.b ${loadaddr} 0xFF <filesystem_image_size> <=== filesystem image size is upward aligned to NAND block size(128k).
U-Boot # mmc rescan
U-Boot # fatload mmc 0 ${loadaddr} base-rootfs-var-som-am33.ubi.img
U-Boot # nandecc hw 2
U-Boot # nand erase 0x00780000 0xF880000
U-Boot # nand write.i ${loadaddr} 0x780000 0xFC0000

From Linux

$ flash_erase /dev/mtd7 0 0
$ ubiformat /dev/mtd7 -f base-rootfs-var-som-am33.ubi.img -s 2048 -O 2048

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)
• gunzip am33-som-nand-recovery-sd.v17.img.gz
• dd if=am33-som-nand-recovery-sd.v17.img of=/dev/sdX bs=128k

Recover Nand Flash

• 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". (This will install Linux on the NAND)
• Unplug the SD card and reboot

NAND recovery script usage:

usage: /sbin/nand-recovery.sh options

This script install Linux/Android binaries in VAR-SOM-AM33 NAND.

OPTIONS:
  -h Show this message
  -o <Linux|Android> OS type (defualt: Linux).

Reference Documentation

• How to Flash Linux System from U-boot
• AMSDK U-Boot User's Guide
• AM335X Flash Programming Guide
• AMSDK Linux User's Guide
  
• AM335X PSP User's Guide
• UBIFS Support