MCSDK OMAPL138 User Guide Chapter Exploring

---

---

MCSDK User Guide for OMAP-L138: Exploring the MCSDK

Last updated: 03/03/2016

---

 Acronyms

The following acronyms are used throughout this chapter.

Acronym	Meaning
CCS	Texas Instruments Code Composer Studio
CSL	Texas Instruments Chip Support Library
DSP	Digital Signal Processor
EDMA	Enhanced Direct Memory Access
EVM	Evaluation Module, hardware platform containing the Texas Instruments DSP
IP	Internet Protocol
JTAG	Joint Test Action Group
MCSDK	Texas Instruments Multi-Core Software Development Kit
PDK	Texas Instruments Programmers Development Kit
TI	Texas Instruments
UART	Universal Asynchronous Receiver/Transmitter
USB	Universal Serial Bus

 ARM Subsystem

Overview

ARM subsystem runs following components:-

   U-Boot - Boot loader

  uImage - linux kernel

  Target File system
This section describes details of these components delivered as part the Linux system in MCSDK.

Linux

          Linux source and prebuilt binary will be available as part of MCSDK package.

prebuilt binary can be found at

mcsdk_<version>
board-support
prebuilt-images
uImage-omapl138-lcdk.bin

The source for the linux is available at 

mcsdk_<version>
board-support
linux-<version>-psp<version>.sdk

The uImage can be built using the source and same can be used for booting the EVM.

1  If you have not already set toolchain, install the arago toolchain for ARMv5te (ARM9) (link to it is in the MCSDK release notes) to a Linux host PC. Add {tool chain install location}/arago-2011.09/armv5te/bin to the exported environment variable 'PATH'. ( refer Getting started Guide for downloading the toolchain)

2  If U-Boot is not built yet, build U-Boot first, as building Linux Kernel requires mkimage utility, which gets built along with U-Boot. Refer to Rebuilding U-Boot for steps to build U-Boot. Once built, mkimage will be present under the tools folder of U-Boot source ( /opt/ti/mcsdk_1_01_00_01/board-support/u-boot--psp\tools<).Ensure that this path is added to the $PATH variable by adding the following

host$ export PATH=/opt/ti/mcsdk_1_01_00_01/board-support/u-boot--psp\tools:$PATH

3 Change directory to linux installation path

host$ cd linux-xx.xx.xx.xx

4 Clean your installation of previous build settings

host$ make distclean ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabi-

5 Configure the kernel according to the default configuration provided. The steps below assume that the arago toolchain is already present in your $PATH variable.

host $ ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabi- make da850_lcdk_defconfig
host $ ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabi- make menuconfig
host $ ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabi- make uImage

More details on linux kernel building is available at

http://processors.wiki.ti.com/index.php/Building_PSP_Components_for_OMAP-L1x_on_v3.x_Kernel#Rebuilding_the_Linux_kernel
More details on Linux PSP is available at

http://processors.wiki.ti.com/index.php/DaVinci_PSP_03.22.00.06_Device_Driver_Features_and_Performance_Guide

U-boot

          U-boot source and prebuilt binary will be available as part of MCSDK package.

prebuilt binary can be found at

mcsdk_<version>
images
   u-boot-omapl138-lcdk.bin

The source for the linux is available at 

mcsdk_<version>
board-support
 u-boot-<u-boot version>-psp<psp version>.sdk

The u-boot can be built using the source and same can be used for booting the EVM.
Follow these steps to rebuild U-Boot:

1. If you have not already done so, install the arago toolchain for ARMv5te (ARM9) on your Linux host.
2. Use your Linux host to build the u-boot source available as part of mcsdk_<version>/board-support/u-boot-<u-boot version>-psp<psp version>.sdk folder
   
3. Go to the u-boot directory .
4. Run the following commands on your Linux host to build U-Boot.

NOTE
The steps below assume that the arago toolchain is already present in your $PATH variable.

for omap-l138 LCDK EVM

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-

The u-boot.bin will be created at the Top folder of the u-boot source as u-boot-<u-boot version>-psp<psp-version>.sdk

This u-boot.bin needs to be converted to AIS file by following the below steps.

       1. Install the AISgen tool  (AISgen_d800k008_Install_<version>).exepresent at

mcsdk_<version>
     host-tools
        aisgen
           windows

       2. Once AIS gen tool is installed at AISgen_d800k008.exe is preset at AISgen for D800K008 folder

       3. Different configuration files are present at AISgen for D800K008\cfg_files

       4. Open the AISgen tool and load OMAPL138_LCDK_AISGen_Config.cfg file

       5. Enable the 'Specify Entrypoint' option and provide the u-boot.bin file path

           pre-built u-boot.bin is present at mcsdk_<version>\images or u-boot.bin built using the u-boot source available as part of mcsdk package

For details of AIS file generation refer

http://processors.wiki.ti.com/index.php/Building_PSP_Components_for_OMAP-L1x_on_v3.x_Kernel#AIS_image_generation_for_omapl138_LCDK_EVM

For details on Flashing u-boot  refer

http://processors.wiki.ti.com/index.php/Running_PSP_Components_on_OMAP-L138_LCDK_EVM#Flashing_images_to_NAND_flash_using_Serial_Flasher

After re-building the u-boot and Kernel image, to program the EVM , to flash the u-boot and boot the EVM with latest kernel refer 

http://processors.wiki.ti.com/index.php/MCSDK_OMAPL138_User_Guide_Chapter_Tools#Loading_and_Running_Application_on_the_target

Target File system

File system is available at

mcsdk_<version>
filesystem

For setting up the Network file system

1. If file system is not already preset ,copy the filesystem on to linux host machine or if mcsdk is installed on linux system,file system can be found at above path.
2. Change directory to file system path
   host $ mkdir -p workdir/filesys
   host $ cd workdir/filesys
   
3. With root user permission , extract the file system
   host $ sudo tar -zxvf tisdk-rootfs-image-omapl138-lcdk.tar.gz  -C workdir/filesys
   
4. Edit the /etc/exports file on the host Linux workstation (not the exports file on the target file system). Add the following line for exporting the filesys directory, substituting your user name for <useracct>. Use the full path from root; ~ may not work for exports on all file systems
   ./home/<useracct>/workdir/filesys *(rw,no_root_squash,no_all_squash,sync)
   

NOTE: Make sure you do not add a space between the * and the ( in the above command.

      5. Still as root, use the following commands to make the NFS server aware of the change to its configuration and to invoke an NFS restart.

            host$sudo /etc/init.d/nfs-kernel-server restart
file system should be ready for use now.

 DSP Subsystem

Overview

The Multicore Software Development Kit (MCSDK) provides the core foundational building blocks that facilitate application software development on TI's high performance and multicore SoC. The foundational DSP components include:

• Chip support libraries, drivers, and basic platform utilities
• Demonstrations and examples

The purpose of this User's Guide is to provide more detailed information regarding the software elements and infrastructure provided with MCSDK. MCSDK pulls together all the elements into demonstrable multicore applications and examples for supported EVMs. The objective being to demonstrate device, platform, and software capabilities and functionality as well as provide the user with instructive examples. The software provided is intended to be used as a reference when starting their development.

Tools Overview

The following documents provide information on the various development tools available to you.

Document	Description
CCS v5 Getting Started Guide	How to get up and running with CCS v5
XDS560 Emulator Information	Information on XDS560 emulator

Hardware - EVM Overview

The following documents provide information about the EVM.           

Document	Description
Detailed information on the LCDK hardware aspect	LCDK Hardware -EVM overview

Platform Development Kit (PDK)

This section gives the information of components of PDK.

While installing the mcsdk_<version>_setupwin32.exe (or mcsdk_<version>_setuplinux.bin) select the PDK_omapl138 for installing PDK. After installing  pdk_OMAPL138_<version> will be get created with list of contents.The following is a more detailed listing of the contents of this folder:

release folder
PDK_OMAPL138_<version>
packages
 ti
   csl
      evm6748
      exampleProjects
   drv
      exampleProjects
      mcasp
      mcbsp

Chip Support Library (CSL)

The Chip Support Library constitutes a set of well-defined APIs that abstract low-level details of the underlying SoC device so that a user can configure and control .The source code for the CSL is located under $(TI_PDK_INSTALL_DIR)\packages\ti\csl directory. The following is the detailed list of PDK CSL example projects available.

    csl
evm6748
exampleProjects
  cache_exampleProject
  gpio_exampleProject
  i2c_exampleProject
  idma_exampleProject
  intc_exampleProject
  mddr_exampleProject
  pllc_exampleProject
  spi_exampleProject
  timer_exampleProject
  uart_exampleProject

Short Description

cache 
This example initializes the CACHE using CSL macros and verifies the same using the bios cache library APIs.

gpio

This example initializes the GPIO peripheral using CSL macros, which are used to configure two GPIO pins one each in input and output modes. The input pin (bank) interrupt is enabled to receive interrupt from that pin when input transition (high to low) occurs at that pin. The interrupt handler registered for this interrupt then toggles the output pin in loop, which make the LED connected at this pin to blink.

i2c

This example uses initializes the I2C peripheral in loopback mode using CSL macros.The data is transmitted and received via this loopback mode using CSL macros.

idma

This example initializes the IDMA peripheral for data transfer using the CSl macros.The source and destination addresses are programmed using the CSL macros and data at the end of transfer is verified.

intc

This example initializes the DSP Interrupt controller using CSL macros. The same is verified by initializing running timer0 to generate an interrupt upon overflow.This is also done using the timer0 CSL

mddr

This example initializes the DDR2/MDDR peripheral using the CSL macros. The settings are then verified by writing and reading to the DDR2/MDDR. The read and written data are compared and a result is output on the console.

pllc

This example initializes the OMAPL138 PLL controller using CSL macros

spi

This example initializes the SPI peripheral in loopback mode using CSL macros.This is verified by comparing the transmit and receive data using CSl macros.

timer

This example initializes the timers 0 and 1 using CSL macros. They are configured to run in one shot mode and generate interrupts upon overflow. The interrupt occurrence are verified in the main function and the result is printed on the console.

uart

This example sets up the UART in 8-bit loopback mode. Characters are transmitted and received using software polling. The test will transmit 8 characters and receive 8 characters and verify the results are correct.

Low Level Drivers (LLDs)

The Low Level Drivers (LLDs) provide ineterfaces to the various peripherals on your SoC Device.
The source code for the LLDs is located under $(TI_PDK_INSTALL_DIR)\packages\ti\drv directory.
following is the detailed list of PDK LLD example projects available

     drv
exampleProjects
MCASP_AudioExampleProject
MCBSP_DigLpbkExampleProject
MCBSP_MasterExampleProject
MCBSP_SlaveExampleProject
mcasp
mcbsp

Short Description

MCASP audio

The sample applications demonstrates the use of the McASP driver by loopback audio capture (the audio fed through Line-in stereo pin from an audio source and playback the audio through the LINEOUT pin on a speaker or headphone).

For Line-in and Line-out pin details refer

http://processors.wiki.ti.com/index.php/LCDK_User_Guide#Block_Diagram_and_Floorplan

MCBSP Digital loopback

The sample application demonstrates the use of the McBSP driver by digital loopback mode of operation, in master mode.

Building and testing Example projects

All the above listed example projects for both CSL and LLDs can be built using ccs and generated .out file can be loaded and run.

Pre-built binaries are also available at 

pdk_OMAPL138_<version>\packages\ti\csl\exampleProjects\bin

pdk_OMAPL138_<version>\packages\ti\drv\exampleProjects\bin

For Building these exampleProjects refer http://processors.wiki.ti.com/index.php/MCSDK_OMAPL138_User_Guide_Chapter_Exploring#DSP.C2.A0example_projects

Details of loading and running can be refered from http://processors.wiki.ti.com/index.php/MCSDK_OMAPL138_User_Guide_Chapter_Tools#Loading_and_Running_DSP_applicaton

Syslink

     syslink source should be available as part of SDK package.

Build Syslink

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 http://processors.wiki.ti.com/index.php/SysLink_Install_Guide

Update all the relevant paths at products.mak for details refer Syslink_Install_Guide

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

host $ make syslink
host $ make samples

While building the syslink with kernel 3.3  which is available as part of mcsdk_1_01_00_02.

mcsdk_<version>
       board-support
             linux-3.3-psp03.22.00.06.sdk

Error as below is observed
/home/test/workspace/ti/syslink_<version>/packages/ti/syslink/utils/hlos/knl/Linux/../../../../../../ti/syslink/family/hlos/knl/omapl1xx/omapl1xxdsp/omapl1xxpwr.c: In function 'OMAPL1XXPWR_attach':
/home/test/workspace/ti/syslink_2_20_02_20/packages/ti/syslink/utils/hlos/knl/Linux/../../../../../../ti/syslink/family/hlos/knl/omapl1xx/omapl1xxdsp/omapl1xxpwr.c:920: error: 'IO_SIZE' undeclared (first use in this function)
/home/test/workspace/ti/syslink_2_20_02_20/packages/ti/syslink/utils/hlos/knl/Linux/../../../../../../ti/syslink/family/hlos/knl/omapl1xx/omapl1xxdsp/omapl1xxpwr.c: In function 'OMAPL1XXPWR_detach':

To build syslink successfully, there are three files in SysLink to which we have to modify the path as mentioned below:

ti/syslink/ipc/hlos/knl/notifyDrivers/arch/omapl1xx/Omapl1xxIpcInt.c

ti/syslink/family/hlos/knl/omapl1xx/omapl1xxdsp/Linux/omapl1xx_phy_shmem.c

ti/syslink/family/hlos/knl/omapl1xx/omapl1xxdsp/omapl1xxpwr.c

Add the following to the above SysLink files:

#undef __ASM_ARCH_HARDWARE_H
#include <mach/hardware.h>

With these changes syslink and examples should build fine.

NOTE : While building syslink and examples if arago toolchain is used then we have update ex33_umsg for correct toolchain

syslink_2_21_01_05/examples/ex33_umsg_ori/linux/Makefile

CFLAGS = CROSS_COMPILE=arm-none-linux-gnueabi- ARCH=arm

to

CFLAGS = CROSS_COMPILE=arm-arago-linux-gnueabi- ARCH=arm

Running SysLink Examples

For running syslink examples first we have copy the same to target file system

host $ make install

or

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

LCDK has to be re-booted with new bootargs.U-Boot arguments can be entered using the "setenv" command

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

setenv bootargs 'console=ttyS2,115200n8 root=/dev/mmcblk0p2 rw rootwait ip=off mem=32M@0xc0000000 mem=64M@0xc4000000'
OR 
setenv bootargs 'console=ttyS2,115200n8 root=/dev/nfs nfsroot=$nfs_serverip:$targetFS_path rw rootwait ip=dhcp mem=32M@0xc0000000 mem=64M@0xc4000000'

After booting with proper bootargs insert syslink.ko and run the examples as below

target# insmod /lib/modules/<kernel_version>/kernel/drivers/dsp/syslink.ko TRACE=1 TRACEFAILURE=1
target# ./runall.sh

Each example contains a readme.txt and run.sh script to demonstrate how to run it.

The root of the samples directory on the target file-system (/ti/syslink-examples/<device>) contains a script to execute all the examples provided.

For details refer

http://processors.wiki.ti.com/index.php/OMAP-L138_LCDK_Linux_Software_Developer%27s_Guide#Running_SysLink_Examples 

Demonstrations

Linux host scripts

The linux host side scripts are available at mcsdk_<version>\bin

setup.sh  will set up your development host for SDK development. All the scripts can be run indivisually as well.

some example host scripts console log is given below

user@linux-host:~/mcsdk_<version>$./setup.sh
-------------------------------------------------------------------------------
TISDK setup script
This script will set up your development host for SDK development.
Parts of this script require administrator priviliges (sudo access).
-------------------------------------------------------------------------------
--------------------------------------------------------------------------------
Verifying Linux host distribution
Ubuntu 10.04 LTS or Ubuntu 12.04 LTS is being used, continuing..
--------------------------------------------------------------------------------

Starting with Ubuntu 12.04 serial devices are only accessible by members of the 'dialout' group.
A user must be apart of this group to have the proper permissions to access a serial device.

User 'x0089162' is already apart of the 'dialout' group

-------------------------------------------------------------------------------
setup package script
This script will make sure you have the proper host support packages installed
This script requires administrator priviliges (sudo access) if packages are to be installed.
-------------------------------------------------------------------------------
System requires packages minicom uboot-mkimage automake to be installed
Installation requires you to have administrator priviliges (sudo access)
on your host. Do you have administrator privilieges?
Type 'y' to continue or 'n' to exit the installation: n
Installation is aborted by user
Failed setup, aborting..

user@linux-host:~/mcsdk_<version>$/bin$ ls

add-to-group.sh

create-sdcard.sh

setup-minicom.sh

setup-targetfs-nfs.sh

setup-uboot-env.sh

common.sh

setup-host-check.sh

setup-package-install.sh

setup-tftp.sh
user@linux-host:~/mcsdk_<version>/bin$./setup-host-check.sh

--------------------------------------------------------------------------------
Verifying Linux host distribution
Ubuntu 10.04 LTS or Ubuntu 12.04 LTS is being used, continuing..
--------------------------------------------------------------------------------
user@linux-host:~/mcsdk_<version>/bin$

DSP example projects

DSP examples can be built using CCSv5. Following are the steps

1. Open the ccs with new workspace
   
2. Select the option File -> Import -> Code Composer Studio -> Existing CCS Eclipse Projects
   
3. select search-directory for the relevant project  and click finish                                                                         
   
4. Once project is opened at Project Explorer
   
5. Check for PDK installation path at project -> properties, If path is not correct , update the same to current installation directory
   

        6.   Update the pdk installation path at Project -> properties - CCS Build - variables PDK_INSTALL_PATH

       7.  Once all the paths are set , Build the project.

For details of loading and running DSP example projects refer

http://processors.wiki.ti.com/index.php/MCSDK_OMAPL138_User_Guide_Chapter_Tools#Loading_and_Running_DSP_applicaton

Trouble Shooting

If the user faces the errors given below when building the MCSDK CSL examples on Ubuntu 12.04LTS,

1. Dependency - Filter Error
2. RTSC error

the following are the work around steps.

Check and set the PATH variables,Linked Resources and few other settings of example project as per the screenshots

open up CCS --> Right click example project --> Linked Resources -->Path Variables -->

particularly the following two path variables should be appropriately set as per the screeshot.

a. BIOS_INSTALL_PATH

b. PDK_INSTALL_PATH

pathVariables

Scr2_LinkedResources

Scr3_RTSC

Scr4_IncludeOptions

This work around is only for building MCSDK CSL examples on Ubuntu 12.04 LTS. For every import of CSL project, this is necessary.

FAQ

---

Q. How to deploy OMAP-L138 MCSDK into Ubuntu 14 ?

---

When installed with Ubuntu 14, the following error message will be thrown without completing the installation.

-------------------------------------------------------------------------------
TISDK setup script
This script will set up your development host for SDK development.
Parts of this script require administrator priviliges (sudo access).
-------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Verifying Linux host distribution
Unsupported host machine, only Ubuntu 10.04 LTS and Ubuntu 12.04 LTS
are supported
Failed setup, aborting..

Ans: In the script file, bin/setup-host-check.sh, comment out the "exit 1" line to proceed with installation.