OMAP-L138 LCDK Linux Software Developer's Guide

 

Welcome to the Software Developer Guide. This page contains information and how-tos for various tasks involved with embedded Linux development using the OMAP-L138 LCDK and its Linux Software Development Kit (SDK). Activities are grouped by the major software components that comes with the SDK. We hope that the content here is helpful to your development on the OMAP-L138 LCDK. Please let us know if you have ideas or suggestions to improve this page and remember to bookmark the LCDK category to receive related update notifications.

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

Supported Platforms and Version Information

PLATFORM	SDK VERSION	STATUS
OMAP-L138 LCDK	1.00.00	Beta

LCDK Linux SDK Getting Started

If you are new to embedded Linux application development, follow the steps outlined in the OMAP-L138 LCDK Linux SDK Getting Started Guide to help jump start the process. It contains information on how to quickly install the SDK, set up the Linux tool chain, perform a confidence build of the "Hello World" program and run it on the LCDK.

OMAP-L138 LCDK Hardware Overview

For detailed information on the LCDK hardware aspect and where to download the schematics, access the LCDK product page or its main wiki page.

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 comand line of the host Linux workstation.

EVM #

Indicates commands to be typed into the U-Boot shell command line from the console window connected to the LCDK board’s serial port.

target $

Indicates commands to be entered into LCDK Linux shell command line, which is usually 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.

General Linux SDK Related Info and Activities

Overview

This SDK contains software and tools to help provide you a quick start in Linux application development for OMAP-L138 using the LCDK. Various components of embedded Linux including the kernel & driver support package, tool chain and file system are provided. Internal to the OMAP-L138 are an ARM9 and a C674 DSP core; both can run up to 456 MHz. On the DSP side, programs can be written to run under TI's SYS/BIOS RTOS or plain C using the DSP libraries and C run-time. Linux applications running on the internal ARM9 core of OMAP-L138 can communicate with the C674 DSP core applications via SysLink Inter-Core Communication (IPC). The Linux-based tools to program the DSP, including SYS/BIOS, SysLink and the C6000 Tool Chain, are included with the SDK for your convenience.

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

OMAP-L138 LCDK Linux SDK Directory Structure

Following is an example of what the top-level folders and files should be found with the SDK and an explanation of its content (in parrentheses).

ti-sdk-omapl138-lcdk-01.00.00
├── bin                             (host utility scripts)
├── board-support                   (linux kernel, u-boot source packages and flashing utils)
├── docs                            (Linux SDK documentation, manifest and licenses)
├── dsp-tools                       (C674-side tools installers)
├── example-applications            (general Linux examples)
├── filesystem                      (ARMv5 root file system tarball for LCDK)
├── host-tools                      (additional host tools)
├── linux-devkit                    (linux development utilties)
├── Rules.make                      (top level SDK environment variable settings)
└── setup.sh                        (top level set-up script helper utility)

NOTE:

As mentioned in the Getting Started Guide "Set Up Paths" procedure, some of the installation scripts for the SDK rely on the environment variable TI_SDK_PATH to know where you have installed the SDK. Please make sure to export it before running the SDK scripts.

Steps to Install the LCDK Linux SDK ARMv5 File System

The supplied Linux file system is derived from the Arago-project, a build system based on Open-Embedded. It is packaged with useful utilties including the bin-utils shell commands, SSH, ALSA, FBdev, etc. The file system is on the second partition of the microSD card as a root file system. On the SDK, the file system comes as a tarball named "omapl138-lcdk-fs.tar.gz" located under the "filesystem" folder.

For development, it is more convenient to set up the file system on your Linux development machine and provide access to the LCDK Linux via NFS.

The following steps describe how to install and export your file system on your Linux host machine.  The SDK comes with a helper script called "setup-target-nfs.sh" that will automate the installation step. The script relies on the top-level "Rules.make" file to give it certain required parameters, the TI_SDK_PATH and DESTDIR variables. Modify these to point to the appropriate locations and run the script as sudo. 

To manually perform the steps, execute the following commands at the top level of the SDK. In the following example, the ARMv5 file system is located under the /home/user/arm9_FS.

host $ cd ~
host $ mkdir arm9_FS
host $ cd arm9_FS
host $ sudo tar xzf $TI_SDK_PATH/filesystem/omapl138-lcdk-fs.tar.gz
host $ sync

To export this file system so the LCDK Linux can mount it, see "export NFS mount".

Linux Kernel & Drivers Related Info and Activities

Overview

The Linux kernel source package includes the kernel, drivers and peripheral stacks as part of a high-level operating system. Activities involving the kernel are usually in customizing the kernel features to select only certain I/Os, stacks or turning on/ off debugging features.

NOTE:

The Linux kernel 3.1.10 that comes with the SDK is a direct port of the open source kernel from kernel.org for the LCDK hardware. What this means is only drivers for peripherals used on LCDK will be provided. If you are looking for other driver examples, consult the reference Linux packages at the OMAP-L138 Linux SDK product folder.

Steps to install and build the Linux kernel for OMAP-L138 LCDK 

The Linux kernel is located under the "board-support" folder. To reduce the size of the SDK, it is a compressed tarball.

To install the OMAP-L138 LCDK Linux kernel, change to your working directory and uncompress the kernel package:

host $ tar xjf $TI_SDK_PATH/board-support/linux-3.1.10-lcdk_v0.bz2

A folder name "linux-3.1.10" should be added to your current directory.

Before building the kernel, remember to add the GCC Tool Chain to your path. You can do this manually or use the GSG's "Set Up Paths" procedure.

Change to the just installed kernel folder. Following is a quick summary of the LCDK kernel build steps for easy reference:

host $ cd linux-3.1.10
host $ ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabi- make distclean
host $ ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabi- make omapl138_lcdk_defconfig
host $ ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabi- make menuconfig
host $ ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabi- make uImage
host $ ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabi- make modules
host $ ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabi- make modules_install INSTALL_MOD_PATH=<your ARMv5 target file system location>

U-Boot bootloader Related Info and Activities

Overview

The U-Boot bootloader for LCDK is a modified version of the U-Boot that comes with the TI PSP 3.21.00.04 Linux package. It is a very popular loader that can boot the Linux kernel from various media including SD/MMC, NAND, TFTP or NFS servers. You can also use U-Boot to perform low level commands such as read/ write to NAND, DDR and load small applications. For more information on u-boot, refer to the U-Boot on-line manual.

Steps to Install and Build U-Boot for OMAP-L138 LCDK

The u-boot package is under the "board-support" folder of the LCDK. To install, untar the package to your working directory.

host $ tar jxf $TI_SDK_PATH/board-support/u-boot-2010.12-psp03.21.00.04.lcdk.bz2

To build u-boot, first make sure the GCC tool chain is set up before running the following build steps. You can do this manually or use theGSG's "Set Up Paths" procedure.

host $ make distclean CROSS_COMPILE=arm-arago-linux-gnueabi-
host $ make omapl138_lcdk_config CROSS_COMPILE=arm-arago-linux-gnueabi-
host $ make all CROSS_COMPILE=arm-arago-linux-gnueabi-

Steps to Boot Linux Using micro-SD card

The micro-SD card shipped with the LCDK comes with multiple partitions as shown in the following table.

PARTITION	CONTENT
1	Linux kernel image
2	ARMv5 LCDK Linux File System
3	Linux and DSP SDKs

The default u-boot bootargs to boot this card is:

bootargs=console=ttyS2,115200n8 root=/dev/mmcblk0p2 rw rootwait ip=off

 

Programming the C674 DSP Related Info and Activities

Overview

The run-time model for the C674 DSP mainly involves applicaitons written as tasks running under SysBIOS RTOS which controls resources such as internal memories and I/Os. SysBIOS is a modular multitasking operating system from TI. More information is available at the SysBIOS product page. Linux applications running on the ARM9 core of OMAP-L138 communicates with SysBIOS applications running on C674 core via SysLink, an Inter-Processor Communication technology from TI. More information on SysLink is available at its wiki page.

Steps to install DSP-related tools

The DSP tools come with their own installer and are under the "dsp-tools" folder of the SDK. The default install folder for these packages are usually "<your home directory>/ti" although any other folder your user ID have R/W/X access permission should work. Once you choose a folder to install, it is desirable to keep all the DSP tools under the same <location>/ti directory to simplify the build settings encounter later, for example with SysLink.

Run all of the installers in the dsp-tools folder.

Following is a listing of the dsp-related packages that come with the current OMAP-L138 LCDK Linux SDK:

dsp-tools
├── bios_setuplinux_6_33_02_31.bin
├── ipc_setuplinux_1_24_02_27.bin
├── syslink_2_10_03_20.tar.gz
├── ti_cgt_c6000_7.3.3_setup_linux_x86.bin
└── xdctools_setuplinux_3_23_01_43.bin

Steps to Build SysLink

Preparation

To setup SysLink, you need to edit the contents of the products.mak file found at the top level of the SysLink folder. This file is used by the SysLink "make" build system to identify which platform to build for and where the supporting tools and headers are located. A detailed procedure is outlined in the SysLink Install Guide wiki page.

Following are settings to help clarify some elements in "products.mak" file.

DEVICE = OMAPL1XX
GPPOS = Linux
SDK = EZSDK
EXEC_DIR = '''<''your ARMv5 target file system location''>'''
LOADER = ELF

DEPOT = /home/'''''<your user ID>'''''

######## For OMAPL1XX device ########
else ifeq ("$(DEVICE)","OMAPL1XX")
LINUXKERNEL = $(DEPOT)/'''''<entire path of your installed linux kernel>'''''/linux-3.1.10
CGT_ARM_INSTALL_DIR = $(DEPOT)/'''''<entire SDK path>'''''/linux-devkit
CGT_ARM_PREFIX = $(CGT_ARM_INSTALL_DIR)/bin/arm-arago-linux-gnueabi-
IPC_INSTALL_DIR = $(DEPOT)/ti/ipc_1_23_05_40
BIOS_INSTALL_DIR = $(DEPOT)/ti/bios_6_32_05_54
XDC_INSTALL_DIR = $(DEPOT)/ti/xdctools_3_22_04_46

If LOADER=ELF then below elf tools path is required else set C674 path
ifeq ("$(LOADER)","ELF")
CGT_C674_ELF_INSTALL_DIR= $(DEPOT)/ti/TI_CGT_C6000_7.3.3
else
CGT_C674_INSTALL_DIR= $(DEPOT)/ti/TI_CGT_C6000_7.3.3

endif

Notice that the related tools rely on the variable DEPOT set up earlier. If you are not installing the TI tools under your home directory, provide the entire path appropriately.

NOTE:

The SysLink build requires the linux kernel build step to be completed successfully at least once so that the proper kernel headers are generated.

Build SysLink

To build SysLink drivers and sample examples, make sure you are in the SysLink folder and run

host $ make syslink
host $ make samples

The next step is installing the SysLink Linux driver and samples to your ARMv5 file system

Running SysLink Examples

To run the sample examples, the driver and executables first need to be transferred to your ARMv5 file system, and reboot the LCDK using adifferent U-Boot bootargs setting than the default version. The following steps will install the Syslink driver and examples to the ARMv5 file system. Again if more details are needed, follow the steps outlined in the SysLink Install Guide wiki.

Installing SysLink Drivers and Examples

To install the drivers and examples, you need the LCKD file system location. If you have not installed the file system, follow "Steps to Install LCDK Linux SDK ARMv5 File System". Otherwise the file system location is either what's specified for variable "EXEC_DIR". The default value will be taken from the products.mak file, but can be overriden by specifying EXEC_DIR=<your ARMv5 file system location>.

NOTE: the file system supplied with the LCDK (on micro-SD card or in the tarball included in SDK) already have the SysLink driver and samples installed. The following steps are in case you want to use Syslink with a custom ARMv5 filesystem or reinstalltion of an updated Syslink.

host $ make install

or

host $ make install EXEC_DIR=<your ARMv5 file system location>

Reboot LCDK with New Bootargs

U-Boot arguments can be entered using the "setenv" command

EVM # setenv <argument line>

The "argument line" to set up u-boot Linux bootargs to be able to run SysLink examples on LCDK is:

bootargs console=ttyS2,115200n8 root=/dev/mmcblk0p2 rw rootwait ip=off mem=32M@0xc0000000 mem=64M@0xc4000000

  

OMAP-L138 LCDK Related Info and Activities

Overview

Sometimes during the course of development you may want to update the u-boot stored on the on-board NAND of the LCDK. The following activities cover the steps for restoring a working u-boot and creating a new version in a compatible format for use with the LCDK.

Restoring U-Boot on a bricked LCDK

If the board does not boot, first check the dip switch SW1 settings to make sure the correct NAND boot mode is set as per the LCDK User's Guide. The LCDK should come with u-boot already flashed. If for some reason U-Boot does not come up, the u-boot flashed on NAND may get corrupted. You can easily restore the LCDK with the pre-built u-boot image  and serial flashing tool included with the LCDK Linux SDK. The prebuilt U-Boot image is u-boot-lcdk_ais.bin and is located under <LCDK Linux SDK install path>/board-support/prebuilt-images. The serial flashing tool is located under <LCDK Linux SDK install path>/host-tools/flash_utils/OMAP-L138_FlashAnd BootUtils_2_40.tar.gz.

Follow the tool documentation to install the utility (MS-Windows or Linux host environment). More information can be found here.

To use the serial flasher, the LCDK SW1 settings needs to be in "Serial Boot Mode". In this mode, the LCDK will boot via the USB serial port. To flash the u-boot image mentioned above using this utility, the command line like below can be used (change COM3 to the correct serial port number for your PC):

sfh_OMAP-L138 -targettype OMAPL138_LCDK -flashtype NAND -p COM3 -flash_noubl u-boot-lcdk_ais.bin

Creating your own U-Boot version that can be flashed on LCDK

If you want to flash your version of U-Boot on LCDK's NAND, the image needs to be converted to AIS format. In this method, the OMAP-L138 internal ROM bootloader (RBL) can load and boot U-Boot without the need to boot a User Boot Loader (UBL) first.

The AIS converter tool can be downloaded from here and is a MS-Windows (tm) install. The tool can import pre-configured files to facilitate the conversion and the LCDK version can be downloaded from this location.

You need to bring the u-boot image to the your Windows PC to use with this tool. The pre-built image of u-boot, u-boot-lcdk.bin, under <LCDK Linux install path/board-support/prebuilt_images, can be used to test out this procedure as well.

Once AISgen is up, import the LCDK config file using File->Load Configuration. The settings should look similar to the following image with some settings not yet set.

 

On "ARM Application File:" entry window, enter the full path of the non-AIS u-boot image file name and its load image address which should be "@0xC1080000" by default (as shown). For the output file, any file name can be used but as good practice, "_ais" is added to differentiate with the non-AIS version if the same name is going to be used.
Next check the "Specify Entrypoint and "Configure PSC" boxes. Under the "PSC" tab, make sure that PCS1 is "13;".

Generate the image and use the serial flasher (as in the restore procedure) to flash the image to NAND on the LCDK.

Linux Host Admin Related Activities

Overview

Embedded Linux development requires the several Linux server services to transfer files, mount file system or to remotely log onto the board running Linux. 

Steps to install TFTP server

TFTP is needed at the U-Boot bootloading stage to retrieve files from the Linux host like the kernel image, ramdisk, etc. TFTP is not considered a secure file transfer method, but it is still commonly used for Linux development. There are several Linux TFTP packages to choose from. The methods here show how to set up the default Ubuntu version and a simple open source version.

TFTP via Default Ubuntu Supported TFTP server

The default Ubuntu tftp server is tftpd-hpa. To see if it is already installed on your system, select "Applications->Ubuntu Software Center" and search for "tftp". If the package is already installed, "HPA's tftp server tftpd-hpa" will be shown. Otherwise use "Get Software" to locate and install the package. 

To make sure tftpd-hpa is running on your system, use

host $ service tftpd-hpa status

If it is already running, the command will return with a process ID

host $ service tftpd-hpa status
tftpd-hpa start/running, process 1354 

Otherwise try reinstalling the package. Sometimes the installation fails because you already have a tftp server running on the sytem but not recognized by the "Ubuntu Software Center" app. If you suspect that this is the case, check for all services running on your Linux host machine to see if there's anything related to "tftp" using:

host $ service --status-all

The tftpd-hpa server uses the location var/lib/tftpboot for the tftp files. To simplify or be consistent with other tftp-related help documentation, you can create a symlink called "tftpboot" that points to that location.

host $ ln -s var/lib/tftpboot tftpboot

Once tftpd-hpa is running, u-boot or even Linux running on the LCDK can retrieve files from this tftp location using the "tftp" command. For example once the Linux kernel was built succesfully, the kernel can be copied to the tftp location so u-boot on LCDK can retrieve it.

Setup TFTP Using the SDK Script

A script named "setup-tftp.sh" is included in the "bin" folder to help automate the tftp set up step. It does not use the Ubuntu supported tftpd-hpa however, but this package is as adequate.

To install, run the script which will check to see whether you already have tftp running and if not, install and set it up for you. Depending on how you set your system permissions, you may need to run this script in sudo mode to access system file settings and commands requiring root priviledges.

Steps to export an NFS mount

This means exposing a folder, usually a file system, located on the Linux host machine so that another Linux machine (the embedded target board) can access. The process involves editing the /etc/exports file and restart nfs server on the host side. On the target EVM, the u-boot bootargs needs to be modified to point to the correct NFS server ip address and folder name. The following wiki page explains these steps in detail. 

How to use SSH to communicate with LCDK

Once Linux is up and running, you can communicate with the LCDK using SSH! Yes there's an SSH server built-in to the LCDK file system. This service is like Telnet, but through a secure connection.

To open an SSH session from your Linux host to your LCDK running embedded Linux and ARMv5 file system, use

host $ ssh root@<ip address of LCDK running Linux>

The Linux host shell will now has a new prompt because you are logged in to the LCDK via Ethernet, which is much faster than the serial connection...