OMAP-L138 LCDK Linux SDK Getting Started Guide

Welcome to the OMAP-L138 LCDK Getting Started Guide (GSG). It's purpose is to walk you through the steps for setting up the OMAP-L138 LCDK Linux Software Development Kit (SDK) on your host Linux development computer. If you are new to embedded Linux and OMAP-L138 LCDK, you should proceed through this guide in the order given for best results. By the end of this Getting Started Guide you will have the Linux host development environment configured to be able to create, compile a "hello world" application, download and run it on the LCDK.

Important Note:

The software found on this site is available for download, but is no longer being actively developed or maintained. To access the latest Linux SW release, visit OMAPL138 MCSDK. To help determine which software option is best for you, visit the OMAPL138 SW & HW Comparison Wiki site

Overview

This Linux SDK was put together to provide you the necessary tools to develop Linux applications on the L138/ C6748 Development Kit (LCDK).

The following table lists the major software components that were included and their purposes:

LCDK Linux SDK Main Software Components

Software Components	Purpose
U-boot source	LCDK Bootloader. Loads Linux kernel from MMC/SD, NAND or NFS
Linux Kernel source	Hi-level operating system with drivers and I/O stacks running on ARM9
ARMv5 File System	Bootable target file system that can be mounted via SD card or NFS
GCC Tool Chain	Open source GNU tools to cross compile ARM target programs
SYS/BIOS	Real-Time OS for C674 DSP
SysLink	Inter-Processor Communication (IPC) software to communicate between Linux and DSP applications
C6x Tool Chain	TI C6000 ISA tool chain to build DSP-side applications

Conventions

Command prompts in this guide

Commands are preceded by prompts that indicate the environment where the command is to be typed. For example:

host $
Indicates command to be typed into the Linux host shell window of the host Linux workstation.
EVM #
Indicates commands to be typed into the U-Boot shell in a console window connected to the LCDK board’s serial port.
target $
Indicates commands to be entered into LCDK Linux shell in the serial terminal window connected to the LCDK board's serial port.

NOTE: The document lists various commands that need to be executed on the target’s Linux shell or on the u-boot prompt. Some of these commands are quite long and may span several lines on this page as one command. These commands will be indicated as “enter as one command”. A direct copy and paste of these commands might result in insertion of line breaks. Hence it would not work on the u-boot prompt or the target. So to be on the safe side, copy these long commands into a text editor (like notepad for Windows™ ), replace the line break between them with a space and then copy and paste it on the command prompts.

Version numbering

Throughout the document, sometimes package names are labeled with xx.xx.xx. This in general is the “major.minor.sub-minor” versioning scheme and should be substituted with the real version number of the same format. For example when the file is ti-sdk-omapl138-lcdk-xx.xx.xx.bz2, the real file could be ti-sdk-omapl138-lcdk-01.00.00.bz2.

SDK Installation

Pre-install Preparation

To begin application development with the LCDK, we recommend the following tools:
- Linux Host machine running Ubuntu 10.04 LTS to build code and as a TFTP and NFS server.
- Serial terminal application e.g. TeraTerm for Windows™ or Minicom for Linux OSes.
- Ethernet cable(s) and optionally a router to act as DHCP server and switch to connect between your Linux host computer and the LCDK.
- Other needed hardware such as VGA monitor, speakers, etc. if your application needs the related peripherals.

The procedures outlined in this GSG assume that you are working with a Linux host machine (i.e. PC). Our reference Linux host version is Ubuntu 10.04 LTS.

If you are new to Linux in general and are looking for information on how to set up Linux host machine, please use the “Linux Host Support” links provided in the “Resource” section below for additional information.

To see the output of Linux running on LCDK, you will need a serial terminal program. Several are available for both Windows ™ (if you are running a virtual Linux machine within Windows) and Linux host environments. The setting should be 115200 baud, 8 bit data, no parity, 1 stop-bit and no flow control. Additional information is provided under “Serial Terminal” of the “Resource” section below.

The router with DHCP server is convenient although not necessary. What’s really needed is a way for the LCDK to connect to your Linux host machine via Ethernet. This can be done using a router with built-in DHCP server and Ethernet switch, or using static IP. If your Linux host machine is in a larger network and the LCDK board can be plugged to this network to get an IP address via DHCP, then only a switch is needed. Once the Linux host machine and LCDK are on the same subnet, they can communicate to each other making it much easier to share file and file systems. These methods will be discussed in later procedures listed in the “Next Steps” section.

A typical embedded Linux development environment set up looks like the following picture:

NOTE: the picture is for a generic EVM. For the LCDK, the null serial cable is replaced by the USB cable. Please refer to the Quick Start Guide booklet included with the LCDK for which port to connect. Not all cables are provided with LCDK.

Obtaining the SDK

A copy of the Linux SDK is provided on the microSD card that comes with the LCDK. It is stored in the 3rd partition. To copy the file to your Linux host machine, put the microSD card into the included SD-card adapter. Insert the adapter via a USB SD card reader or SD-card slot of your Linux machine. Depending on how you configured your Ubunty Linux host machine, usually 3 windows will be automatically opened, one for each partition. This indicates that the partitiions are automatically mounted and ready to be accessed. If this does not happen, you need to use the Linux "fdsisk -l" or "dmesg | tail" command to check how the card was detected (the USB SD-card reader may register as /dev/sd<drive letter> like /dev/sdb, while the SD card reader slot may register as /dev/sdc<n>, e.g. /dev/sdc1>. The 3rd partition containing the SDK is a FAT32 partition, so it needs to be mounted as a vfat partition in Linux.

You can also download the SDK from the LCDK product folder listed in your LCDK Quick Start Guide booklet included with the LCDK.
The file name should read something like ti-sdk-omapl138-lcdk-xx.xx.xx.bz2 where xx.xx.xx is the version number. For example a version of the SDK install file is "ti-sdk-omapl138-lcdk-01.00.00.bz2".

NOTE: Removing the microSD card which is inserted in the LCDK while Linux is running may damage the content of the filesystem since there could be pending file I/O operations. The cleanest way to do this before removing power to the LCDK is by executing a “shutdown” command at the serial terminal window as in the following line.

target $ shutdown –h now

A series of messages will be outputted on the screen. Wait for this activity to cease before removing power to the LCDK. The microSD card can now be removed safely from the board.

Linux SDK Installation Steps

The SDK can be installed to any directory in your home folder. For example if you downloaded the SDK to your "Downloads" folder, the following command will uncompress the SDK in the current directory:

host $ tar jxf ~/Downloads/ti-sdk-omapl138-lcdk-xx.xx.xx.bz2

A folder ti-sdk-omapl138-lcdk-xx.xx.xx (where xx.xx.xx will be substituted with the actual version number) should be created in the current directory as the result.

Following is an example of what the top-level folders and files should be found with the SDK.

ti-sdk-omapl138-lcdk-01.00.00
├── bin
├── board-support
├── docs
├── dsp-tools
├── example-applications
├── filesystem
├── host-tools
├── linux-devkit
├── Rules.make
└── setup.sh

More details for these folders are available with the LCDK Linux SDK Software Developer's Guide. The next step is to set up the Linux build tools and verify its correct operation.

Setup and Verify Linux Tool Chain

Set up paths

To set up the tool chain paths, change to the just installed SDK directory and use the following procedure.

1) Export SDK Installation Path
The setup scripts provided with the SDK relies on the environment variable TI_SDK_PATH to know where you have installed the SDK. To make this known, use the “export” command on the host machine.

For example if you install the SDK under a folder titled "SDKs", the export command will look like

host $ export TI_SDK_PATH=/home/user/SDKs/ti-sdk-omapl138-lcdk-01.00.00

You can make this step automatic by adding this export command to your shell setup file. For bash shell, edit the file .bashrc to include this export line.

 - Edit Rules.make (optional)
This file contains the paths that will be used by the “setup” script that you may need later so it is a good time to update your SDK path to be consistent.
Using the same example, the updated TI_SDK_PATH line in “Rules.make” file will be:

# Points to the root of the TI SDK
export TI_SDK_PATH=/home/user/SDKs/ti-sdk-omapl138-lcdk-01.00.00  

2) Run the environment set up script:

A script called "environment-setup" is included to help automate the setting of other needed environment variables for development. To start it, run the following command:

host $ source linux-devkit/environment-setup

The script will change the shell prompt to start with “linux-devkit” followed by the current directory. Using the same example, after execution the prompt should change to

[linux-devkit]:~/SDKs/ti-sdk-omapl138-lcdk-01.00.00> 

3) Verify that your path has been updated to include the GCC tool chain provided by the SDK using the command:

host $ echo $PATH

The listed path should include the <sdk-install-path>/linux-devkit/bin of the just installed SDK.

You can also test the compiler by checking the version using

host $ arm-arago-linux-gnueabi-gcc --version

which should return something like the following:

arm-arago-linux-gnueabi-gcc (GCC) 4.5.3 20110311 (prerelease)
Copyright (C) 2010 Free Software Foundation, Inc. 
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Edit and compile "Hello World!"

Now that the Linux tool chain is in place, you can quickly whip up the “Hello World!” program to perform a confidence build. Cut and paste the following program to your favorite Linux text editor (for Ubuntu the default editor is gedit) and save the file as hello.c

 #include <stdio.h>
 int main(void)
 {
     printf ("Hello World! LCDK\n");
     return 0;
 }  

Cross-compile the program:

host $ arm-arago-linux-gnueabi-gcc hello.c –o hello

Booting Linux on LCDK using Pre-installed Binaries

Your LCDK should come with the boot-loader u-boot pre-installed. The provided microSD card contains a default Linux kernel and an ARMv5 file system designed for the LCDK. Setup the LCDK and boot up Linux as described in the “Quick Start Guide” booklet included with the LCDK.
Note: the procedure below involves switching back and forth between the host linux shell (indicated by host $) and the LCDK linux shell (indicated by target $) in the serial terminal window.

Transfer and Run "Hello World!" application to LCDK 

At the serial terminal window, enter the following command to find out the IP address of the board:

target $ ifconfig

Once the IP address is known, use SCP to transfer the file to the LCDK. For example the following command entered on your Linux host shell will drop the “hello” executable to the “/home/root” folder on the LCDK (make sure you substitute <LCDK IP address> with the actual one):

host $ scp hello root@<LCDK IP address>:/home/root/

To verify that the file has been transferred OK, on the serial terminal window, list the /home/root directory content to check:

target $ cd /home/root
target $ ls 

The output should look like the following:

root@omapl138-lcdk:~# ls
hello

Now run the application by executing it in the serial terminal window:

target $ ./hello 

Note that in actual the interaction and result should look more like this:

root@omapl138-lcdk:~# ./hello
Hello World! LCDK
root@omapl138-lcdk:~#

Congratulations!

At this point, you have successfully
- Installed the LCDK Linux SDK
- Set up and verified the embedded Linux development Cross-Compile tool chain
- Created, downloaded and ran a Linux application on the OMAP-L138 LCDK board
You now have a running embedded Linux system based on the OMAP-L138 SoC and can develop applications for it. You can continue using this method to develop Linux applications to run on the LCDK, or explore more advanced procedure such as using NFS to mount the file system, customizing the Linux kernel, and writing applications that can communicate with signal processing programs running on C674 DSP core using the link listed in the “Next Steps” section.

Next Steps

More advanced procedures are listed in the LCDK Linux SDK Software Developers Guide 

Resource

OMAP-L138/ C6748 Product Information

 TI OMAP-L138 SoC product folder  
 TI OMAP-L138/ C6748 Product Introduction Wiki link 

Linux Host Support

Ubuntu Linux Host Configuration steps Host Configuration - Ubuntu How-to 

Virtual PC for Ubuntu Linux using VirtualBox  
Virtual PC for Ubuntu Linux using VMware  

Serial Terminal

TeraTerm for Windows ™ OS
Minicom help page for Linux