Example application using DSP Link on OMAPL1x legacy

This page is provided to help developers use peripherals directly from the DSP side when using OMAP-L1x family of devices. Since it uses extensively DSP/Link and DSP/BIOS as well as the POOL memory allocator, it is highly desirable to have a good understanding on these software technologies.

Note: This is an example application and is provided as-is but is being continuously improved. Please check back anytime.

Introduction

For many developers that have extensive background on TI DSPs, going to an ARM+DSP processor platform usually imposes a difficult learning curve due to the complexity of the interactions between a High Level Operating System (HLOS) and the familiar DSP/BIOS - not to mention the different development environment (usually Linux).

In order to help with such big learning curve, this article covers in detail an example application that not only loads and runs the DSP from the ARM (using the PROC mechanism of DSP/Link) but also allows the DSP to access hardware peripherals directly (either via CSL or BSL). It also shows a safe method of sharing memory (POOL) and passing control messages (Message Queue or MSGQ) between the two operating systems - Linux on the ARM and DSP/BIOS on the DSP.

Required Software:

• Code is located here:

https://www-a.ti.com/downloads/sds_support/applications_packages/helloDSP/index.htm (requires my.ti.com registration)

• • File <helloDSPgpp.tar.gz> is the ARM side application.
  • File <helloDSPdsp.tar.gz> is the DSP side application.
  • File <modules.tar.gz> contains precompiled DSP/Link linux modules.

• The tools below are available at the myRegisteredSoftware page (requires my.ti.com registration):
• OMAPL137 SDK; (this example was tested with 1.00.00.09 SDK)
• DSP/BIOS 5.33.x (this example was tested with 5.33.03)
• Code Generation Tools 6.1.x (this example was tested with 6.1.9)
• EVMOMAPL137 Test Code from Spectrum Digital: http://support.spectrumdigital.com/boards/evmomapl137/

Useful references:

This article extensively uses the following references:

• DSP/Link overview: DSPLink_Overview

• DSP/Link API guide and examples:

<DSPLink_install_dir>/packages/dsplink/doc/UserGuide.pdf

• Section 6.5 of DSP/BIOS User's Guide SPRU403

• Sections 2.19 and 2.21 of DSP/BIOS API Guide for C6000 SPRU423

• Example code for MSGQ supplied by DSP/BIOS releases:

%BIOS_INSTALL_DIR%/packages/ti/bios/examples/advanced/msgq_tsk2tsk

• POOL API guide: chapter 6 of

<DSPLink_install_dir>/packages/dsplink/doc/design/LNK_082_DES.pdf

Outside of the scope of this article is the setup of the Linux machine and the development environment. For details on how to do this, please check:

• Before the Getting Started Guide: Before_the_Getting_Started_Guide
• OMAPL137 Getting Started Guide: Getting_Started_Guide_for_OMAP-L137

Overview

The example application is comprised (obviously) of two main processes: a Linux application that loads and starts the DSP using PROC calls, as well as exchanges messages and data through message queues (MSGQ) through a shared memory region configured using POOL; a DSP/BIOS application that starts its execution after being loaded by the Linux application and a task (TSK) receives and sends back messages to it using the same MSGQ and POOL structures. The messages exchanged contain simple Integer commands (0x01 and 0x02) and an Array of Chars that carries the string messages between the two processors.

In essence it is a heavily modified (and simplified) MESSAGE example supplied by DSP/Link, but the concepts are the same. Additional details can be seen in chapter 17 of the DSP/Link User's Guide for details on the example workflow.

ARM side application

For easier comprehension, the ARM side contains three source files:

• <main.c> contains the Linux entry point and simply performs the initial error checking of the command line parameters
• <system_os> contains an abstraction layer between the code and the Linux operating system. This way it can be easily ported to other operating systems (WinCE, etc).
• <helloDSP.c> contains the bulk of the application:
  • Function helloDSP_main(): Application entry point that contains the sequence of function calls for this module, as well as the data verification checking.
  • Function helloDSP_Create(). The allocator and starter function, the most intricate part of the code. Configures the DSP through PROC_setup() and PROC_attach(). Creates the memory pool using POOL_open() and opens the control message queue between the two cores; this queue not only holds the control messages via a MSGQ_open() but also holds any asynchronous error messages via MSGQsetErrorHandler(). In sequence, it loads the DSP using PROC_load() and starts its execution via PROC_start(), in order to be able to open the transport mechanism (MSGQ_transportOpen()) and wait for the first message to arrive from DSP using MSGQ_locate().
  • Function helloDSP_Execute(). The main execution body. After receiving the first DSP message (the first MSGQ_get()), it simply replies back to the DSP the same message queue. Optionally (by defining PROFILE and VERIFY_DATA) it can display the number of iterations passed via command line and verify the data received. At this point it is a good idea to insert any custom code for data processing and send the message back to the DSP, using MSGQ_put().
  • Function helloDSP_Delete(). The de-allocator function. Closes the remote transport and stops DSP execution. It also closes the MSGQ and removes the PROC object from memory. Here the sequence is important, since it must happen in reverse order done by helloDSP_Create().

DSP side application

In the DSP side there are also three source files:

• <main.c> contains the DSP main function call that initializes DSP/Link (DSPLINK_init()), the BSL (EVMOMAPL137_init()) and creates the main application task (tskMessage) that contains the application sequence of events;
• <helloDSP_config.c> contains the memory Pool and the Message queue configurations. These configurations match the ones performed by the file <helloDSP.c> for the ARM core;
• <tskMessage.c> contains the bulk of the application:
  • Function TSKMESSAGE_create(). The allocator and starter function. Allocates memory for the DSPLink physical transport mechanism via MEM_calloc() and starts the message queue semaphore using SEM_new(). In sequence, similarly to what happens in the ARM side, it creates the message queue MSGQ_open() and sets the error handling queue MSGQ_setErrorHandler(). At last, it waits for the first sync signal from the ARM through MSGQ_locate().
  • Function TSKMESSAGE_execute(). The main execution body. It sends the first message MSG_put() back to ARM and runs through a loop as many times as passed to the application via the command line. In this loop it runs the main application (the led_test() routine) and writes to the message queue buffer the the message that indicates the end of each iteration. At the end of the loop, the message is sent back to the ARM via the last MSG_put().
  • Function TSKMESSAGE_delete(). The de-allocator function. Releases the message queue (to avoid further communications) and closes it. At last it frees the memory used by the remote transport and returns to the main application task (tskMessage()). This task finishes and returns to the DSP/BIOS Idle loop.

Installation and usage

Requirements

• As mentioned in the Required Software section above, the application requires all the components (OMAPL137 SDK, DSP/BIOS, Code Generation Tools, BSL, ARM compiler tools) to be installed in a Linux host PC. Check the section Installing the Software for OMAPL137 on the OMAPL137 Getting Started Guide for details on how to do it.
• It also requires a target board running linux and a way to transfer files to/from the host PC (NFS mount, USB pendrive or SD card, etc.).

Installation procedures

The example application is supplied in two files: <HelloDSPdsp.tar.gz> for the DSP and <HelloDSPgpp.tar.gz> for the ARM. Extract both to the desired working directory on the host PC.

• These files also contain precompiled binaries (executables) for OMAPL137. The executables must be copied to the target board filesystem.

The DSP executables are located at: <./Debug/helloDSP.out> or <./Release/helloDSP.out>

The ARM executables are located at: <./Debug/helloDSPgpp> or <./Release/helloDSPgpp>

Before running any DSP/Link application, it is also necessary to load its corresponding linux module on your target board.

• A precompiled module <dsplinkk.ko> is supplied with the SDK installation at:

<DSPLink_install_dir>/packages/dsplink/gpp/export/BIN/Linux/OMAPL1XX/RELEASE

• For convenience, the file <modules.tar.gz> contains the module (as well as additional modules that allow for additional functionality).
• This module can also be rebuilt using the methods described in the Getting Started Guide - section Building the OMAP-L137 SDK.
• The module must be copied to the target board filesystem as well.

Running the supplied binaries

From the target board command prompt, the application can be executed as follows:

• Load the DSP/Link module first. If the modules were copied from the provided <modules.tar.gz> file:

./loadmodules.sh

• If the module <dsplinkk.ko> was copied from the SDK, then additional steps are required:

insmod dsplinkk.ko

rm -f /dev/dsplink

mknod /dev/dsplink c 230 0

• At last, execute the application:

./helloDSPgpp helloDSP.out 2

The number "2" in the command above specifies the number of iterations the DSP main routine will execute.

The screen would show something similar to:

root@192.168.1.79:/opt# ./helloDSPgpp helloDSP.out 2
========== Sample Application : helloDSP ==========
Entered helloDSP_Create ()
Leaving helloDSP_Create ()
Entered helloDSP_Execute ()
Message received: DSP is awake!
Message received: Iteration 0 is complete.
Message received: Iteration 1 is complete.
Transferring 2 iterations took 0 seconds 254132 microseconds.
RoundTrip Time for 1 message is 127066 microseconds.
Leaving helloDSP_Execute ()
Entered helloDSP_Delete ()
Leaving helloDSP_Delete ()
====================================================
root@192.168.1.79:/opt#

Note that there is a time measurement for the message passing, and probably the 127066 microseconds seems very large for a simple memory copy operation. However, this value also takes into consideration the total time of the operations including the LED blinking execution time - a much slower process. If desired, these measurements may be prevented by removing the definition -DPROFILE from the CFLAGS variable of the GPP side makefile:

#   ----------------------------------------------------------------------------
#   General options, sources and libraries
#   ----------------------------------------------------------------------------
SRCS := helloDSP.c system_os.c main.c
OBJS :=
DEBUG :=
LDFLAGS := -lpthread
CFLAGS := -DPROFILE
LIBS :=
BIN := helloDSPgpp

Additional steps for building

To build the application, it is necessary to download the EVMOMAPL137 Test Code package from the Spectrum Digital website. This package contains the Board Support Library (BSL) and the LED blinking source code.

• Unzip this package in any directory of choice - this application assumes it is installed together with the TI tools in /opt/ti/boards directory. This package is typically installed in a Windows environment under C:\CCStudio_v3.3\boards\omapl137_v1.
• In order to build the application successfully, copy the file <led_test.c> located under dsp/tests/led to the working directory of the DSP side application - helloDSPdsp.

At last, before moving on to the build process make sure the Makefiles for both the DSP and the GPP contain the correct installation directories of the Linux compiler, TI's CGT tools, DSP/BIOS, DSP/LINK and BSL.

NOTE: If you followed the Getting Started Guide for OMAP-L137, you will have to set the proper directories in the makefiles.

HelloDSPdsp

For example, in the DSP side makefile changes should be needed at the following places:

• TI's tools directories

#   ----------------------------------------------------------------------------
#   Base for TI toolchain
#   This may change depending if you are using other versions of the compiler
#   ----------------------------------------------------------------------------
BASE_TOOLCHAIN := /opt/ti
BASE_COMPILER := $(BASE_TOOLCHAIN)/c6000/cgt619
BASE_SABIOS := $(BASE_TOOLCHAIN)/bios_5_33_03
BASE_BSP:= $(BASE_TOOLCHAIN)/boards/evmomapl137_v1

If you followed the Getting Started Guide for OMAP-L137, please change it to:

#   ----------------------------------------------------------------------------
#   Base for TI toolchain
#   This may change depending if you are using other versions of the compiler
#   ----------------------------------------------------------------------------
BASE_TOOLCHAIN := /home/user/OMAPL137_arm_1_00_00_10
BASE_COMPILER := $(BASE_TOOLCHAIN)/cg6x_6_1_9
BASE_SABIOS := $(BASE_TOOLCHAIN)/bios_5_33_05
BASE_BSL := $(BASE_TOOLCHAIN)/boards/evmomapl137_v1

NOTE: This assumes that you downloaded the evmomapl137_v1 folder from Spectrum digital and placed it at /home/user/OMAPL137_arm_1_00_00_10/boards/

• DSP/Link base directory

#   ----------------------------------------------------------------------------
#   Base for DSPLink
#   This may have to be changed depending on your installation paths
#   and DSPLink version
#   ----------------------------------------------------------------------------
DSPLINK := /opt/OMAPL137_arm_1_00_00_09/dsplink-1_61_03-prebuilt/packages/dsplink

If you followed the Getting Started Guide for OMAP-L137, please change it to:

#   ----------------------------------------------------------------------------
#   Base for DSPLink
#   This may have to be changed depending on your installation paths
#   and DSPLink version
#   ----------------------------------------------------------------------------
DSPLINK := $(BASE_TOOLCHAIN)/dsplink-1_61_03-prebuilt/packages/dsplink

Important! Due to a bug in DSP/BIOS 5.33.05, you will have to add executable permissions to the <tconf> and <tconf.x86U> files in the bios directory. For example:

• cd /home/user/OMAPL137_arm_1_00_00_10/bios_5_33_05/xdctools
• chmod +x tconf
• chmod +x tconf.x86U

You can then recompile the DSP side code using:

• gmake clean
• gmake

HelloDSPgpp

In the ARM side makefile, changes should be needed at the following places:

• Linux toolchain

#   ----------------------------------------------------------------------------
#   Base for toolchain
#   This may change depending if you are using Montavista or Codesourcery
#   ----------------------------------------------------------------------------
BASE_TOOLCHAIN := /opt/mvl_pro_5_0_0/montavista/pro/devkit/arm/v5t_le
#BASE_TOOLCHAIN := /opt/arm/arm-2007q3       # Codesourcery tools

#   ----------------------------------------------------------------------------
#   Name of the Linux compiler
#   This may change depending if you are using Montavista or Codesourcery
#   ----------------------------------------------------------------------------
CC := arm_v5t_le-gcc
#CC := arm-none-linux-gnueabi-gcc

If you followed the Getting Started Guide for OMAP-L137, please change it to:

#   ----------------------------------------------------------------------------
#   Base for toolchain
#   This may change depending if you are using Montavista or Codesourcery
#   ----------------------------------------------------------------------------
BASE_TOOLCHAIN := /opt/mv_pro_5.0/montavista/pro/devkit/arm/v5t_le
#BASE_TOOLCHAIN := /opt/arm/arm-2007q3       # Codesourcery tools

#   ----------------------------------------------------------------------------
#   Name of the Linux compiler
#   This may change depending if you are using Montavista or Codesourcery
#   ----------------------------------------------------------------------------
CC := arm_v5t_le-gcc
#CC := arm-none-linux-gnueabi-gcc

• DSP/Link installation directory

#   ----------------------------------------------------------------------------
#   Base for DSPLink
#   This may have to be changed depending on
#   your installation and DSPLink version
#   ----------------------------------------------------------------------------
DSPLINK := /opt/OMAPL137_arm_1_00_00_09/dsplink-1_61_03-prebuilt/packages/dsplink

If you followed the Getting Started Guide for OMAP-L137, please change it to:

#   ----------------------------------------------------------------------------
#   Base for DSPLink
#   This may have to be changed depending on
#   your installation and DSPLink version
#   ----------------------------------------------------------------------------
DSPLINK := /home/user/OMAPL137_arm_1_00_00_10/dsplink-1_61_03-prebuilt/packages/dsplink

The application can be built simply by running make or gmake from the command line. For example:

• gmake clean
• gmake

Using the re-compiled DSP/Link libraries

If you followed the procedure to re-compile the DSP/Link libraries in Building_The_OMAP-L137_SDK and want to use them to rebuild this application, please be sure that the correct include library directories are set in the Makefiles.

In the DSP side Makefile, the lines below must be changed from:

#   ----------------------------------------------------------------------------
#   Linker library search path for Debug
#   ----------------------------------------------------------------------------
LDINCLUDES_D := $(LDINCLUDES) -i$(DSPLINK)/dsp/export/BIN/DspBios/OMAPL1XX/OMAPL1XXGEM_0/DEBUG/

#   ----------------------------------------------------------------------------
#   Linker library search path for Release
#   ----------------------------------------------------------------------------
LDINCLUDES_R := $(LDINCLUDES) -i$(DSPLINK)/dsp/export/BIN/DspBios/OMAPL1XX/OMAPL1XXGEM_0/RELEASE/

To:

#   ----------------------------------------------------------------------------
#   Linker library search path for Debug
#   ----------------------------------------------------------------------------
LDINCLUDES_D := $(LDINCLUDES) -i$(DSPLINK)/dsp/BUILD/OMAPL1XXGEM_0/EXPORT/DEBUG/

#   ----------------------------------------------------------------------------
#   Linker library search path for Release
#   ----------------------------------------------------------------------------
LDINCLUDES_R := $(LDINCLUDES) -i$(DSPLINK)/dsp/BUILD/OMAPL1XXGEM_0/EXPORT/RELEASE/

Also, if you followed the entire DSP/Link rebuild procedure you will have to include an additional library called <dsplinkdata.lib> on the DSP-side. Therefore add -ldsplinkdata.lib to the LIBS flag - check the fully modified line below:

LIBS := -ldsplink.lib -ldsplinkpool.lib -ldsplinkmpcs.lib -ldsplinkmplist.lib -ldsplinkmsg.lib -ldsplinknotify.lib -ldsplinkringio.lib -ldsplinkdata.lib -levmomapl137bsl.lib

In the GPP side Makefile, the only need is to point to the correct library. Locate the flags LIBS_D and LIBS_R:

LIBS_D := $(DSPLINK)/gpp/export/BIN/Linux/OMAPL1XX/DEBUG/dsplink.lib $(LIBS)

LIBS_R := $(DSPLINK)/gpp/export/BIN/Linux/OMAPL1XX/RELEASE/dsplink.lib $(LIBS)

And change them to:

LIBS_D := $(DSPLINK)/gpp/BUILD/EXPORT/DEBUG/dsplink.lib $(LIBS)

LIBS_R := $(DSPLINK)/gpp/BUILD/EXPORT/RELEASE/dsplink.lib $(LIBS)

Important! When copying the application to the target board, don't forget to also copy the recently compiled DSP/Link linux module <dsplinkk.ko>. It is located in the two directories above, together with <dsplink.lib>

Modifying the example application

The most obvious modification is to insert custom code in the main DSP code execution inside the TSKMESSAGE_execute() routine.

In file <tskMessage.c> look for the SYS_sprintf() calls that populate the message queue with data to be passed to the ARM side:

• At or around line 160

<syntaxhighlight lang="c"> if (status == SYS_OK) {

 MSGQ_setMsgId((MSGQ_Msg) msg, info->sequenceNumber);
 MSGQ_setSrcQueue((MSGQ_Msg) msg, info->localMsgq);
 msg->command = 0x01;
 SYS_sprintf((Char*)msg->arg1, "DSP is awake!");
(...)

</syntaxhighlight>

• At or around line 210

<syntaxhighlight lang="c"> else {

 /* Include your control flag or processing code here */
 /* LED test code from Board Support Library example  */
 led_test();
 msg->command = 0x02;
 SYS_sprintf((Char*)msg->arg1, "Iteration %d is complete.", i);
(...)

</syntaxhighlight>

Also, different types of messages can be passed between the two cores by modifying the struct ControlMsg. Any modifications must be done simultaneously in the files <helloDSP_config.c> on the DSP side and <helloDSP.c> on the GPP side.

<syntaxhighlight lang="c"> typedef struct ControlMsg {

 MSGQ_MsgHeader header;
 Uint16 command;
 Char* arg1[ARG_SIZE];

} ControlMsg; </syntaxhighlight>

To probe further

No application can really be considered finished, therefore some additional features and things to try can greatly add to the example shown above:

• Use the ability of accessing hardware from the DSP side to add PWM output capabilities;
• Add to the GPP side a menu-based application to better control the DSP operation;
• Add additional DSP/BIOS tasks and semaphores instead of simply adding function calls to TSKMESSAGE_execute() to perform additional functionality;
• There are still some lines in the source code (especially in the GPP side) that are inherited from the multi-device approach of the DSP/Link examples, but these were ignored for this first release.
• Any additional ideas?

Troubleshooting

• If you are getting an error similar to the screenshot below, it is probably due to the fact the DSP/Link Linux module was not loaded. Simply follow the instructions in the section above named Running the supplied binaries.

root@192.168.1.79:/opt# ./helloDSPgpp helloDSP.out 2
========== Sample Application : helloDSP ==========
Entered helloDSP_Create ()
dsplink driver open: /dev/dsplink: No such file or directory
PROC_setup () failed. Status = [0x80008008]
Leaving helloDSP_Create ()
Entered helloDSP_Delete ()
Assertion failed (IS_VALID_MSGQ (msgqQueue)). File : msgq.c Line : 484
MSGQ_release () failed. Status = [0x8000800b]
Assertion failed (((drvObj != NULL) && (IS_OBJECT_VALID (drvObj, SIGN_DRV))) ||
((drvObj == NULL) && (cmdId == CMD_PROC_ATTACH))). File : drv_api.c Line : 509
Assertion failed (IS_VALID_MSGQ (msgqQueue)). File : msgq.c Line : 335
Leaving helloDSP_Delete ()
====================================================
root@192.168.1.79:/opt#

• The numbers that follow the PROC_setup() call above are very important and indicate the cause of DSP/Link failure. Please check the page Understanding_DSPLink_error_codes for details.