Software Manual (Diva)

Info Box Applies to Diva

Introduction

Major software components of an Embedded Linux system are:

• bootloader
• operating system kernel
• root file system, including user-space application and libraries
• tool chain (on development host)
• build system (on development host)

Diva Embedded Linux Kit: what is it?

Diva Embedded Linux Kit (DIVELK for short) provides all the necessary components required to set up the developing environment to:

• build the bootloader (U-Boot)
• build and run Linux operating system on Diva-based systems
• build Linux applications that will run on the target.

The kit is composed by:

• hardware platform composed by Diva system-on-module (SOM for short) and carrier board. Supported carrier boards are:
  • DivaEVB-Lite
  • SOM-EVB carrier board
• U-Boot bootloader sources
• Linux kernel sources
• Technical documentation such hardware manuals, mechanical drawings, reference schematics, application notes etc.

The documents related to the software issues help the user to quickly start configuring the bootloader and the operating system, by hiding most of the complexity of the underlying hardware. For more details about Diva hardware characteristics, please refer to the Diva Hardware Manual. An account for the reserved area of DAVE's website is required to access the kit contents.

Diva Embedded Linux Kit: what is not?

The kit is neither a complete Linux programming guide nor a Linux Reference Guide. Internet provides lots of information, tutorials and examples about writing applications and drivers for this operating system and how to work with it from the user's point of view (for example, type “Linux programming” in your favorite search engine). As the kit is heavily based on open-source community-maintained software projects, DIVELK does not provide exhaustive documentation for these software components but it points out where to find the information on the Internet or books. For example, for the U-Boot bootloader, the kit does not list all the commands it handles but provides the link to the on-line documentation and to the public mailing list used by its community.

For novice users who have no experience at all with embedded Linux systems, reading article Embedded Linux is recommended.

About this manual

This document describes how to run Linux on the Diva/DivaEVB-Lite/Carrier-board system. For novice users who have no experience at all about embedded Linux systems, reading of Building Embedded Linux Systems By Karim Yaghmour is strongly recommended. Practically speaking, the book covers all matters involved in developing software for such systems (from tool-chain organization to the most famous file systems running on top of MTD). It is not a reference guide, but it provides a complete and exhaustive overview that helps the developer save a lot of time in searching for such information on the Internet. For a brief but still exhaustive overview of the Linux and Embedded Linux world, please look at the Training and Docs sections of Free Electrons website.

Support service

We are committed to making our products user-friendly and will help customers use our CPU modules in their systems. Technical support is delivered through email. Support requests can be sent to support-diva@dave.eu. Software upgrades are available in the restricted download area of DAVE web site: http://www.dave.eu/reserved-area. An account is required to access this area (please contact support-diva@dave.eu for account requests). Please refer to our Web site at http://www.dave.eu/dave-cpu-module-am335x-diva.html for the latest product documents, utilities, drivers, Product Change Notices, Board Support Packages, Application Notes, mechanical drawings and additional tools and software.

DIVELK overview

Components

Diva SOM

The heart of Diva SOM is Texas Instruments "Sitara" AM335x microprocessors. From a software point of view, Texas Instruments supports this processor family through so-called Linux EZ Software Development Kit (EZSDK for short). EZSDK releases are published on a regular basis. For more details please refer to:

• http://www.ti.com/tool/linuxezsdk-sitara
• http://processors.wiki.ti.com/index.php/Category:EZSDK

Diva Embedded Linux Kit, in turn, is directly derived from EZSDK. Hence DIVELK documentation often refers to EZSDK resources.

Carrier boards

DivaEVB-Lite is an adapter board designed to evaluate the functions of Diva system-on-module.

DivaEVB-Lite provides the following interfaces:

• On board peripherals:
  • SPI NOR flash
  • 1x UART RS232 on DB9 connector
  • 1x Ethernet port on RJ45 connector
  • 1x USB 2.0 port on MiniAB connector
  • I/Os on expansion connectors
  • 12V power connector
• Routed to J1 and J2 (140-pin) connectors:
  • 18-bit RGB LCD
  • 1x SD/MMC
  • 1x SPI
  • 2x UART
  • 2x I2C
  • JTAG
  • 2x USB
  • 1x McASP
  • Touch screen / AD signals

The following figure shows the carrier board block diagram

Software

When we talk in general about Embedded Linux, we refer to an embedded system running Linux operating system. As the reader probably knows, Linux was first developed on the PC platform, based on the famous x86 architecture. Typical embedded systems using an operating system (O.S. for short), are equipped with much lighter software. Recent hardware advances made these systems so powerful that now they can run a complex O.S. such as Linux. This choice has several benefits:

• The developer can count on a reliable and efficient software, developed and maintained by a large community all over the world
• The software is open-source, so developers have access to the whole source code
• Since Linux runs on many different platforms (x86, PowerPC, ARM, SuperH, MIPS etc.), applications are portable by definition
• There are a lot of open-source applications running on top of Linux that can easily be integrated in the embedded system
• Last but not least, there are no license fees.

An exhaustive description of this topic is beyond the scope of this document. We recommend reading specific documents, eg Building Embedded Linux Systems By Karim Yaghmour. The typical Embedded Linux system is composed of:

1. the bootloader – this software is run by the processor after exiting the reset state. It performs basic hardware initialization, retrieves the Linux kernel image (for example from a remote server via the TFTP protocol) and launches it by passing the proper arguments (command line and tags)
2. the Linux kernel
3. the root file system – this file system is mounted (which means "made available", "attached") by the kernel during the boot process on the root directory (“/”).

The typical developing environment for an Embedded Linux system is composed of a host machine and a target machine. The host is used by the developer to compile the code that will run on the target. In our case the target is obviously the Diva module, while the host is assumed to be a PC running the Linux operating system. The Linux kernel running on the target can mount the root file system from different physical media. During the software development, we strongly recommend using a directory exported via NFS by the host for this purpose (see the example configuration called net_nfs).

DIVELK components

Dave adds to the latest EZSDK from Texas Instruments the customization required to support the Diva platform. For this reason most of the documentation provided by TI remains valid for the DIVELK development kit. However, some customization is required, in particular at bootloader and linux kernel levels.

The following table shows how NELK releases are related to EZSDK releases.

	DIVELK version
Release number	1.0.0
Status	Planned
Release date	May 2013
Release notes	Ver 1.0.0
SOM PCB version
Supported carrier boards
U-Boot version
Linux version
Drivers
TI EZSDK	5.0? (release date?)

DIVELK contains all the required software to develop Linux application on the Diva platform

• Virtualbox virtual machine image with pre-installed Ubuntu Linux and pre-configured basic Linux services (Tftp, NFS, ...)
• Virtualbox disk containing source code and tools:
  • Bootloader (u-boot) source tree cloned from DAVE's public git repository
  • Linux kernel source tree cloned from DAVE's public git repository
  • Pre-installed AM335x EZSDK with setup scripts, makefiles, example applications, ...
  • Toolchain

Please note that DIVELK u-boot and kernel source trees are derived from the official trees released by TI; these trees have been customized to add support for the Diva SOM.

For further information on EZSDK, please refer to Sitara SDK release notes.

Release notes

DIVELK 1.0.0

• Release date: May 2013
• Status: planned
• EZSDK version: 5.0?.??.??
• Supported carrier boards: DivaEVB-Lite, Dacu

Notes

• First official release

Developing environment

Introduction

The following figure show the typical developing environment for an Embedded Linux system: it is composed of a host machine and a target machine.

The typical developing environment for an Embedded Linux system is composed of a host machine and a target machine. The host is used by the developer to (cross-)compile the code that is to run on the target. In our case the target is the Diva CPU module, while the host is assumed to be a PC running the Linux operating system, either in a physical installation or as a virtual machine. The bootloader running on the target can download the Linux kernel image through the network (tftp), as well as the u-boot binary images (useful when an update of the bootloader is required). Moreover, the Linux kernel running on the target is able to mount the root file system from different physical media, for example from a directory exported via Network File System (NFS) by the host. This strategy (kernel image and RFS retrieved from the network) saves time during the development phase, since no flash reprogramming or removable storage (SD, usb pen drives, external disks) is required to test new versions or updates of the software components.

Software components

Toolchain

With the term "toolchain" we refer to the set of programs that allow the building of a generic application. For applications built to run on the same platform as the tool chain, we use a native toolchain. On the contrary, for applications built to run on a target architecture different from the host architecture, we use a cross-toolchain. In this case all the tools involved in this process are lead by the “cross-” prefix. So we talk about cross-compiler, cross-toolchain and so on. The cross-toolchain used to build U-Boot and the Linux kernel is the GNU toolchain for the ARM architecture built for x86 hosts. In other words, the toolchain runs on x86 machines but generates binaries for ARM processors. As for all the software compliant to the GPL license, it is released in source code. Thus the first thing to do to set up the developing environment should be building the cross-toolchain. This is not a trivial task, it takes a lot of time and hard disk space. To avoid this tedious task, we suggest use of a pre-built toolchain as explained in the following sections.

Bootloader

U-Boot is a very powerful boot loader and it became the "de facto" standard on non-x86 embedded platforms. The main tasks performed by U-Boot are:

1. hardware initialization (external bus, internal PLL, SDRAM controller etc.)
2. starting a shell on the serial port allowing the user to interact with the system through the provided commands
3. automatic execution of the boot script (if any)

After system power-up, U-Boot prints some information about itself and about the system it is running on. Once the bootstrap sequence is completed, the prompt is printed and U-Boot is ready to accept user's commands. U-Boot manages an environment space where several variables can be stored. These variables are extremely useful to permanently save system settings (such as ethernet MAC address) and to automate boot procedures. This environment is redundantly stored in two physical sectors of boot flash memory; the default variables set is hard-coded in the source code itself. User can modify these variables and add new ones in order to create his/her own custom set of configurations. The commands used to do that are setenv and saveenv. This process allows the user to easily set up the required configuration. Once U-Boot prompt is available, it is possible to print the whole environment by issuing the command printenv.

For further information on use of U-Boot, please refer to http://www.denx.de/wiki/view/DULG/UBoot

Kernel

Linux kernel for Sitara processors is maintained primarily by Texas Instruments, that constantly carries on a major effort to works in close cooperation with Linux community in order to push all the released drivers into mainstream kernel. Periodically TI releases the so-called Platform Support Product (PSP for short). PSP provides updated kernel sources.

Kernels released within DIVELK derive directly from PSP kernels.

For further information on Linux for TI processors, please refer to http://processors.wiki.ti.com/index.php/Category:Linux

Target root file system

The Linux kernel running on the target needs to mount a root file system. Building a root file system from scratch is definitively a complex task because several well known directories must be created and populated with a lot of files that must follow some standard rules. Again we will use pre-packaged root file systems that make this task much easier.

DVDK

Dave Virtual Development Kit is a virtual machine, based on Oracle VirtualBox that allows developers to start using Dave's platform without wasting time in installing the development environment. The Virtual Machine comes with all the development tools and source code, pre-configured, and requires only a minimal setup by the end user (usually only to adapt network interface to the user environment).

DVDK can also be converted, easily, into a physical environment, for example to increase speed on slower machines.

Please refer to DVDK page on Dave Developer's Wiki for further information on DVDK.

Quick start

DivaEVB-Lite

This section describes how to quick start a DivaEVB-Lite system, provided that it is programmed according to DIVELK configuration.

1. connect the serial cable, provided with the board, to J6
2. connect this cable to PC COM port through a NULL-modem cable (not provided)
3. start your favourite terminal software on PC; communication parameters are:
   • baud rate: 115200 Bps
   • data bits: 8
   • stop bits: 1
   • parity: none
4. (optional) to connect the system to Ethernet LAN, please plug cable on connector J7
5. connect a 12Vcc power supply to J8

Once power has been applied, U-Boot bootloader will be executed and the following messages will be printed on serial console (please note that messages may vary for different U-Boot releases)

U-Boot 2010.06-dirty (May 29 2012 - 16:02:39) [nelk-0.9.0-min]       

TI8148-GP rev 2.1

ARM clk: 600MHz
DDR clk: 400MHz

DRAM:  512 MiB
Using default environment

Hit any key to stop autoboot:  0 
8192 KiB AT45DB642D at 0:0 is now current device
## Starting application at 0x81000000 ...


U-Boot 2010.06-dirty (May 29 2012 - 15:57:21) [nelk-0.9.0]

TI8148-GP rev 2.1

ARM clk: 600MHz
DDR clk: 400MHz

I2C:   ready
DRAM:  512 MiB
NAND:  HW ECC Hamming Code selected
1024 MiB
MMC:   OMAP SD/MMC: 0
Net:   Detected MACID:d4:94:a1:8e:68:24
cpsw
Hit any key to stop autoboot:  0 
NAON#

These messages are printed by U-Boot, which has a serial console that allows basic interaction with the system.

At the end of its boot sequence, U-Boot prints DIVA# prompt and waits for user commands.

The default u-boot environment can be printed using the print command:

NAON#print
bootcmd=run net_nfs
bootdelay=3
baudrate=115200
autoload=yes
verify=yes
bootfile=naon/uImage
ramdisk_file=ramdisk.gz
loadaddr=0x81000000
spi_update_1st=sf probe 0:0; sf erase 0x0 0x20000; sf write ${loadaddr} 0x0 0x20000
spi_update=sf probe 0:0; sf erase 0x20000 0x40000; sf write ${loadaddr} 0x20000 0x40000
loadk=tftp ${loadaddr} ${bootfile}
spi_updatek=sf probe 0:0; sf erase 0x80000 0x300000; sf write ${loadaddr} 0x80000 0x300000
console=ttyO0
addcons=setenv bootargs ${bootargs} console=${console},115200n8 earlyprintk
addmem=setenv bootargs ${bootargs} mem=${mem} vram=${vram} notifyk.vpssm3_sva=${notify_mem}
addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gateway}:${netmask}:${hostname}:${ethdev}
nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} panic=5
net_nfs=run loadk nfsargs addip addcons addmem; bootm ${buf}
nandargs=setenv bootargs root=/dev/mtdblock12 rw rootfstype=jffs2
spi_nand=run nandargs addip addcons addmem; sf probe 0:0; sf read ${loadaddr} 0x80000 0x300000; bootm ${loadadd}
mmcargs=setenv bootargs root=/dev/mmcblk0p1 rw
spi_mmc=run mmcargs addip addcons addmem; sf probe 0:0; sf read ${loadaddr} 0x80000 0x300000; bootm ${loadaddr}
ipaddr=192.168.0.77
serverip=192.168.0.23
netmask=255.255.255.0
gateway=192.168.0.254
hostname=naon
rootpath=/home/shared/devel/dave/naon-DAA/sw/linux/sdk/rfs/nelk
ethdev=eth0
mem=176M
vram=46M
notify_mem=0xBF900000
ethaddr=d4:94:a1:8e:68:24
ethact=cpsw
spi_load_1st=tftp ${loadaddr} naon/u-boot.min.spi
load=tftp ${loadaddr} naon/u-boot_new.bin
stdin=serial
stdout=serial
stderr=serial

Environment size: 1588/65532 bytes

Build system

Introduction

A build system is a set of source trees, Makefiles, patches, configuration files, tools and scripts that makes it easy to generate all the components of a complete embedded Linux system. A build system, once properly set up, automates the configuration and cross-compilation processes, generating all the required targets (userspace packages (libraries, programs), the kernel, the bootloader and root filesystem images) depending on the configuration. Some well known build systems are the following:

• Arago (http://arago-project.org/wiki/index.php/Main_Page)
• OpenEmbedded (http://wiki.openembedded.net/index.php/Main_Page)
• Yocto (https://www.yoctoproject.org/)
• Buildroot (http://buildroot.uclibc.org)

Setting up the server environment

During development, user needs to interact with the target system. This section describes the tools that must be installed and configured on the host system for this purpose. Please note that all these tools are already installed and properly configured on the virtual machine image provided with the DIVELK.

TFTP Server

One of the most useful features of a bootloader during development is the capability to download the Linux kernel from the network. This saves a lot of time because developer doesn't have to program the image in flash every time he/she modifies it. U-Boot implements the TFTP protocol (see the tftp command), so the host system must be configured to enable the TFTP service. Installation and configuration of a tftp server depends on the host Linux distribution.

NFS Server

One of the most important components of a Linux system is the root file system. A good development root file system provides the developer with all the useful tools that can help him/her on his/her work. Such a root file system can become very big in size, so it's hard to store it in flash memory. User could split the file system in different parts, mounting them from different media (flash, network, usb...). But the most convenient thing is to mount the whole root file system from the network, allowing the host system and the target to share the same files. In such a way, the developer can quickly modify the root file system, even “on the fly” (meaning that the file system can be modified while the system is running). The most common way to setup a system like the one described is through NFS. As for tftp, installation and configuration depends on the host linux distribution.

Pre-built toolchain

To start developing software for the Diva platform, users need a proper toolchain, which can be pre-built or built-from-scratch. Building a toolchain from scratch is not a trivial task (though using a recent build system is easier than in the past), so the recommended approach consists in using a pre-built toolchain, like the Sourcery G++ Lite 2009q1-203 for ARM GNU/Linux. To install it, user should simply download the installer from the http://www.codesourcery.com/sgpp/lite/arm/portal/release858 web page and run it.

At the time of this writing several tool chains – free and commercial – are available. The Codesourcery toolchain (Sourcery G++ Lite 2009q1-203 for ARM GNU/Linux (http://www.codesourcery.com/sgpp/lite/arm/portal/release858)) will be the default choice and all the compiling examples will be based on it.

Pre-built root file system

Linux needs a root file system: a root file system must contain everything needed to support the Linux system (applications, settings, data, ..). The root file system is the file system that is contained on the same partition on which the root directory is located. The Linux kernel, at the end of its startup stage, mounts the root file system on the configured root device and finally launches the /sbin/init, the first user space process and "father" of all the other processes. An example of root file system is shown below:

drwxr-xr-x  2 root     root     4096 2011-05-03 11:23 bin/
drwxr-xr-x  2 root     root     4096 2011-04-01 17:20 boot/
drwxr-xr-x  3 root     root     4096 2011-07-07 12:17 dev/
drwxr-xr-x 44 root     root     4096 2011-05-03 19:02 etc/
drwxr-xr-x  4 root     root     4096 2011-04-01 17:35 home/
drwxr-xr-x  5 root     root     4096 2011-05-03 11:23 lib/
drwxr-xr-x 12 root     root     4096 2011-07-07 12:03 media/
drwxr-xr-x  6 root     root     4096 2011-05-19 16:39 mnt/
drwxr-xr-x  2 root     root     4096 2011-03-11 05:21 proc/
drwxr-xr-x  2 root     root     4096 2011-05-03 11:23 sbin/
drwxr-xr-x  2 root     root     4096 2011-03-11 05:21 sys/
lrwxrwxrwx  1 root     root        8 2011-05-30 12:19 tmp -> /var/tmp/
drwxr-xr-x 11 root     root     4096 2010-11-05 19:36 usr/
drwxr-xr-x  8 root     root     4096 2010-12-12 11:30 var/

For more information on the Linux filesystem, please refer to The Linux filesystem explained

DIVELK provides a pre-built root file system, that can be used during the evaluation/development phase, since it provides a sufficient set of packages for working with the Diva platform. However, there are other pre-built file systems that can be used:

• Arago (http://arago-project.org/files/releases/)
• Angstrom/Narcissus (http://www.angstrom-distribution.org/narcissus/)
• Beaglebone (http://www.angstrom-distribution.org/demo/beaglebone/)

Basic setup

Once the installation is completed, the directory structure is the following:

The bin directory contains the tool chain binaries. GNU Compiler Collection (GCC) version is .....

Once the toolchain is installed, it is recommended to create a file (for example ~/diva/env.sh) on host containing the following lines:

export PATH=~/diva/arago-2012.10/bin:$PATH
export ARCH=arm
export CROSS_COMPILE=arm-arago-linux-gnueabi-

By issuing the following command, some environment shell variables will set up in order to make building procedures described later easier to handle:

source ~/diva/env.sh

The last step is to create the directory /tftpboot/DIVELK/diva that will be used to download the kernel via the tftp protocol, as explained in section 4.3.1.

Further information about the AM35xx platform can be found here: http://wiki.davincidsp.com/index.php/Category:AM35x

Build/configure Linux kernel

Enter the Linux sources directory (~/diva/linux-am33x.git) and run the following commands:

dvdk@dvdk-vm:~/diva/linux-am33x.git$ make diva_defconfig
dvdk@dvdk-vm:~/diva/linux-am33x.git$ make uImage

The former command select the default Diva configuration, while the latter build the kernel binary image with the required u-boot header.

Default linux kernel configuration can be changed by using the standard menuconfig, xconfig, gconfig make target.

Subsequent builds just require uImage make target to update the binary image.

Build/configure U-Boot only

Enter the Linux sources directory (~/diva/u-boot-am33x.git) and run the following commands:

dvdk@dvdk-vm:~/diva/u-boot-am33x.git$ make diva_spiboot
dvdk@dvdk-vm:~/diva/u-boot-am33x.git$ make

The former command select the default Diva configuration which is used to boot from SPI NOR Flash, while the latter build the u-boot binary images.

Subsequent builds just require make command, without targets, to update the binary images.

U-boot is composed by two binary images called:

• MLO (which is called also SPL or 1st stage)
• u-boot.img (which is the main u-boot image, plus an additional header needed by SPL)

Boot configurations

Flash_self

This configuration is conceived for standalone operation. Both the kernel and the root file system are retrieved from Flash (see section 2.4). Once U-Boot has transferred the control to Linux, its job is completed. From now on Linux kernel has the control of the hardware. At the end of Linux boot process, the user can interact with the system with the typical Unix-like shell through the same serial connection used for U-Boot. To run this configuration just issue the command run flash_self.

Ethernet interface will be enabled by default. To disable it, just remove addip variable from the flash_self variable.

Net_nfs

This configuration is very helpful during the software development (both for kernel and applications). The kernel image is downloaded via TFTP while the root file system is remotely mounted via NFS from the host. It is assumed that the development host:

• is connected with DivaEVB through an Ethernet LAN
• exports the directory containing the root file system for the Diva system through the NFS server
• runs a TFTP server.
• has 192.168.0.23 as IP address (netmask 255.255.255.0).

If the host system does not match this configuration, it's required to change the necessary u-boot variables and store them permanently with the saveenv command. For example, let's say the server has different IP address, eg 192.168.0.72:

=> setenv serverip 192.168.0.72 
=> saveenv 
Saving Environment to NAND... 
Erasing Nand... 
Erasing at 0x0 -- 2490368% complete. 
Writing to Nand... done 
=>

To run this configuration, just issue the command following command:

run net_nfs

Automatic boot

If you wish Diva system to automatically boot with one of the above configurations, just set up and store the bootcmd variable. For example, for the flash_self configuration, enter the following commands:

=> setenv setenv bootcmd $(flash_self)
=> setenv serverip 192.168.0.72 
=> saveenv 
Saving Environment to NAND... 
Erasing Nand... 
Erasing at 0x0 -- 2490368% complete. 
Writing to Nand... done 
=>

Next time the system boots, U-Boot will wait for three seconds (to stop the wait just press any key in the console) before executing the commands stored in the bootcmd variable. This time can be changed by setting the bootdelay variable. Generally speaking the whole boot process can be further and heavily customized. For more details please refer to the doc/README.autoboot file in the U-Boot sources.