DM816x EZ Software Developers Guide
DM816x EZ Software Developers Guide
DM816x EZ Software Developers Guide
Contents
• 1 Welcome to the DM816x EZSDK Software Developer's Guide
• 2 Starting your software development
♦ 2.1 Setting up the EZ SDK
♦ 2.2 Writing your own "Hello World!" application and executing
it on the target
• 3 Running the pre-installed applications on the target file system
♦ 3.1 Running Audio applications
♦ 3.2 Running the SysLink examples
♦ 3.3 Running the Codec Engine examples
♦ 3.4 Running the Qt/Embedded examples
♦ 3.5 Running the Graphics SDK examples
♦ 3.6 Running GStreamer pipelines
♦ 3.7 Running the RPE examples
• 4 Using the devkits
♦ 4.1 Regenerating the devkits
♦ 4.2 Verifying the devkit integrity
♦ 4.3 Moving the devkits
• 5 EZSDK software overview
♦ 5.1 Creating a Linux application
♦ 5.2 Creating a SYS/Link application
♦ 5.3 Creating an OpenMax IL application
♦ 5.4 Creating a Qt/Embedded application
♦ 5.5 Matrix User's Guide
♦ 5.6 Creating a GStreamer application
◊ 5.6.1 Compiling a GStreamer application
• 6 Additional Procedures
♦ 6.1 Setting up cross compilation environment
♦ 6.2 Modifying the EZSDK Memory Map
♦ 6.3 How to setup the EZ SDK for DDR2 EVMs
♦ 6.4 Rebuilding the EZ SDK components
♦ 6.5 Creating your own Linux kernel image
♦ 6.6 Setting up Tera Term
♦ 6.7 How to create an SD card
♦ 6.8 How to display a logo at boot
Note! This Software Developer's Guide (SDG) supports version 5.05 of the DM816x EZSDK which is only
for Linux host development.
Note! All instructions in this guide are for Ubuntu 10.04 LTS and Ubuntu 11.10. At this time, these are the
only supported Linux host distributions for development.
Note! In previous DVSDK releases there has been a Getting Started Guide explaining how to set up the
DVSDK. This document replaces and extends the Getting Started Guide for DVSDK 3.xx and is a new
document in the EZSDK superseding the Getting Started Guide.
Throughout this document there will be commands spelled out to execute. Some are to be executed on the
Linux development host, some on the Linux target and some on the u-boot (bootloader) prompt. They are
distinguished by different command prompts as follows:
target # <this command is to be executed on the target> u-boot :> <this command is to be executed on the
u-boot prompt>
The EZ SDK comes with a script for setting up your Ubuntu 10.04 LTS development host as well as your
target boot environment. It is an interactive script, but if you accept the defaults by pressing return you will
use the recommended settings. This is recommended for first time users. Note that this script requires ethernet
access as it will update your Ubuntu Linux development host with the packages required to develop using the
host $ ${EZSDK}/setup.sh
If you accepted the defaults during the setup process, you will now have set up your development host and
target to:
1. Boot the Linux kernel from your development host using TFTP. On your development host the Linux
kernel is fetched from /tftpboot by default.
2. Boot the Linux file system from your development host using NFS. On your development host the
Linux target file system is located at ${HOME}/targetfs
3. Minicom is set up to communicate with the target over USB-UART (J6). If you want to use a
windows host for connecting to the target instead, see the #Setting_up_Tera_Term section.
Note! To boot the board from NFS, you may need to change the boot switch settings on your EVM. Please
refer the UBoot user guide in the board-support/docs folder for more information on the switch settings.
If you start minicom on your Linux development host using minicom -w (or Tera Term on Windows) and
power cycle the EVM, Linux will boot.
After Linux boots up, login into the target using root as the login name.
Note! The Matrix application launcher is launched automatically. If you exit from Matrix and if you would
like to start it again, execute the following command on the target board:
Make sure you have terminated the Matrix before running any other applications from the command line:
1. Create your own work directory on the host PC and enter it:
#include <stdio.h>
int main()
{
printf("Hello World!\n");
}
# Import the variables from the EZSDK so that you can find the EZSDK components
include ${EZSDK}/Rules.make
helloworld:
# Make sure that you use a tab below
$(CSTOOL_PREFIX)gcc -o helloworld helloworld.c
Save the file and exit. Note that the gap before $(CSTOOL_PREFIX)gcc corresponds to a tab. If it is filled
with spaces instead you will get build errors.
This command should print your EZSDK installation directory. If it doesn't, you will have to set it again as
described in the beginning of this document. Compile the application:
5. You now have your own application, but you need to create a directory and copy it to your NFS exported
filesystem to make it visible by the target:
target # /home/root/dm816x/helloworld
Hello World!
Congratulations! You now have your own basic application running on the target.
Writing your own "Hello World!" application and executingit on the target 4
DM816x EZ Software Developers Guide
Before running these ensure that Matrix application is not running. This can be done by executing the
following command in the serial terminal.
If you wish to restart the Matrix application at a later time, you can execute the following command.
Note! The syslink samples use a different memory map from the default EZSDK installation. In order to run
syslink examples, you must boot with a different memory for linux. When booting, ensure that the linux
bootargs is changed from the default values to MEM=169M
Note! The syslink samples cannot be run out with graphics or firmware loaded. Please execute the following
steps to teardown the graphics plane and ensure that no firmware is running.
The target terminal window will output the results of the examples executed.
Note! To run other examples, go to corresponding example folder and execute ./run.sh.
Note! The syslink samples use a different memory map from the default EZSDK installation. In order to run
syslink examples, you must boot with a different memory for linux. When booting, ensure that the linux
bootargs is changed from the default values to MEM=169M
Note! The Codec Engine examples cannot be run out with graphics. Please execute the following steps to
teardown the graphics plane and ensure that no firmware is running.
To run the application, enter the following set of commands on the target:
target # cd /usr/share/ti/ti-codec-engine-examples
Ensure that syslink and cmem modules are installed with memory configuration as below
To run the audio1_copy example, you will need to run the following commands.
target # cd audio1_copy
target # ./app_remote.xv5T
target # cd /usr/bin/qtopia/examples
target # ls
Note! - You should quit the Matrix GUI application before running Qt/Embedded examples.
target # cd /usr/bin/qtopia/examples/richtext/calendar
target # ./calendar -qws -geometry 320x200+50+20
target # cd /usr/bin/SGX/demos/Raw
target # ls
OGLES2Water OGLESOptimizeMesh
OGLESCoverflow OGLESParticles
Execute the following command to run 3D Graphics application, this particular example is for an album
coverflow.
target # ./OGLES2Coverflow
After you see the output on the display interface, hit q to terminate it
Note: In order to see the video output, the graphics planes need to be turned off. By default, graphics plane 0
is tied to HDMI, graphics plane 1 is tied to HD DAC and graphics plane 2 is tied to SD. For more information
on the graphics planes and their sysfs entries, please read the VPSS guide in PSP documentation.
In case Graphics Planes 1 and 2 are currently open, then they need to be disabled as well. This is only required
if the video output needs to be directed to the HD-DAC or SD displays.
The following pipeline decodes a H.264 Elementary Stream and displays it to HDMI:
1. Go to the directory, where the RPE example and firmware binary are present.
target # cd /usr/share/ti/rpe
2. Load the DSP firmware binary with the codec configurations using the firmware loader.
3. Run the AAC-LC decoder example with the sample media and configuration file.
1. The tools, libraries and headers to develop applications for a specific hardware subsystem (e.g. the
arm or the dsp).
2. The devkits are relocatable, meaning you can move them to another location on your filesystem and
they will still work (see #Moving the devkits below).
3. The devkits do not contain source code or build files. If you want to change components, or make a
change to a component, the devkit will need to be regenerated, see #Regenerating the devkits below.
4. The devkits contain the documentation of the TI components in one location.
The devkits were introduced to provide a more unified view of what is available for each hardware subsystem
and present a system view of the software in the EZSDK as opposed to a component view. Since they are
relocatable, they are also easier for a user to check in to version control.
Note! The components themselves are still available from the ${EZSDK}/component-sources directory, and
the ${EZSDK}/Rules.make file still points to all the right component directories. If you do not wish to build
against the devkits, but directly against the components, this is still possible.
If you have modified a component, in which case the support TI will be able to provide is limited, you can
regenerate the devkits using only the last 7 steps above.
Note that not all components contribute to all devkits. You may only have to regenerate e.g. the dsp-devkit if
you update or change sysbios.
In addition, the ${EZSDK}/docs directory contains the md5sums of the devkits at the time of release.
If a file has been changed, or a component updated, the md5sums will have changed. To verify whether this is
the case for e.g. the dsp-devkit, enter the dsp-devkit directory and execute:
If there is no output from this command, your integrity with the devkit released by TI is ok. If there is an
error, the offending files will be printed.
1. If you want to be able to regenerate the dsp-devkit (see #Regenerating the devkits, you'll need to
update the DSP_DEVKIT_DIR variable in ${EZSDK}/Rules.make.
2. Before building against the dsp-devkit from the command line, you need to "source" the
environment-setup script (don't forget the .):
host $ . /path/to/dsp-devkit/environment-setup
Note! For the linux-devkit you will currently have to edit the first line of
${EZSDK}/linux-devkit/environment-setup to change the SDK_PATH variable to point to your new location.
You can get your new location by executing the following in the linux-devkit directory:
host $ pwd
Note! The dsp-devkit does not contain xdctools. If you need to relocate the devkit, the path to xdctools needs
to be updated in dsp-devkit/environment-setup.
Note! After relocating the devkits, Rules.Make must be updated. Please update CODEGEN_INSTALL_DIR,
LINUX_DEVKIT_DIR and DSP_DEVKIT_DIR according to their new locations on your filesystem.
The EZ SDK contains many software components. Some are developed by Texas Instruments and some are
developed in and by the open source community(White). TI contributes, and sometimes even maintains, some
of these open source community projects, but the support model is different from a project developed solely
by TI.
While creating a basic Linux application you are typically using the following components of the stack (the
rest are greyed out above):
You can find examples all over the web on how to write this type of application. The PSP examples are a
good reference on how to access the peripheral drivers specific to this platform.
SYS/Link(SysLink) is foundation software for the inter-processor communication across the HLOS-RTOS
boundary. It provides a generic API that abstracts the characteristics of the physical link connecting HLOS
and RTOS from the applications. It eliminates the need for customers to develop such link from scratch and
allows them to focus more on application development.
SysLink provides several features and capabilities that make it easier and more convenient for developers
using a multi-core system:
In addition to the components used for the basic Linux app, these are used (and the rest is greyed out in the
diagram above):
multiprocessor systems
C6000 Code
TI DSP code generation tools dsp-devkit/cgt6x_x_x_xx
Generation Tools
Good application examples to start from include:
The OpenMax IL package wraps key Multimedia functions which can be invoked from the ARM side using
simple API calls. In addition to the components used for the Linux app, these are used (and the rest is greyed
out in the diagram above):
Qt/Embedded is a Graphical User Interface toolkit for rendering graphics to the Linux framebuffer device, and
is included in this kit. The base Qt toolkit on the other hand renders the graphics to the X11 graphical user
interface instead of to the basic framebuffer.
In addition to the components used for the basic Linux app, these are used (and the rest is greyed out in the
diagram above):
Compiling an application
EZ SDK Linux development kit includes the Qt/Embedded host tools and development header and libraries.
2. Next, follow the typical Qt/e recommended method for cross compiling your application on host.
GStreamer is an open source multimedia framework which allows you to construct pipelines of connected
plugins to process multimedia content. The gst-openmax plugin accelerates multimedia using OpenMax.
Compared to creating an application directly on top of OMX you get the advantage of A/V sync and access to
many useful open source plugins which e.g. allows you to demux avi-files or mp4-files. The downside is
increased complexity and overhead.
In addition to the components used for the OMX app, these are used:
To construct your own pipelines there are examples of how to use the open source plugins in various places
on the web including the GStreamer homepage at gstreamer.ti.com.
See the GStreamer Application Development Manual and the GStreamer 0.10 Core Reference Manual on how
to write GStreamer applications.
EZSDK Linux development kit includes the GStreamer development header files, libraries and package
configs.
2. Next, follow the typical GStreamer recommended method for compiling your application. e.g.
Additional Procedures
Setting up cross compilation environment
To enable your application development, EZ SDK comes with linux-devkit which contains package header,
libraries and other package dependent information needed during development. Execute the following
commands to configure your cross compilation environment
The above command will export cross compilation specific environment variables.
You will notice that the command will add [linux-devkit] to your bash prompt to indicate that you have
exported the required cross compiler variables.
host $ cd $EZSDK/board-support/u-boot-YYYY.MM-pspxx.yy.zz.pp
host $ vi arch/arm/include/asm/arch-ti81xx/clocks_ti816x.h
Comment the line defining DDR_PLL_796 and add following line to the clocks_ti816x.h
Additional Procedures 18
DM816x EZ Software Developers Guide
//#define DDR_PLL_796
#define DDR_PLL_400
host $ vi include/configs/ti8168_evm.h
Uncomment the DDR2 config and comment the DDR3 config macros
//#define CONFIG_TI816X_EVM_DDR3
#define CONFIG_TI816X_EVM_DDR2
host $ cd ${EZSDK}
host $ make u-boot
This will build the MLO, u-boot.bin and u-boot.noxip.bin files. These u-boot files need to be used instead of
the default DDR3 image. They can be copied over to the board-support/prebuilt-images directory. Please
follow procedures on how to build an SD Card if you would to create an SD Card image for your DDR2
EVM.
Note: The EZ SDK component build environment is self contained and doesn't require the
#Setting_up_cross_compilation_environment thus should be avoided to prevent possible build failures.
Rebuild the EZSDK components by first entering the EZ SDK directory using:
host $ cd ${EZSDK}
The EZ SDK makefile has a number of build targets which allows you to rebuild the EZSDK components. For
a complete list execute:
Some of the components delivered in the EZ SDK are not pre-built. The provided 'make clean' & 'make
components' build targets are designed to clean and build all components (e.g. Linux Kernel, CMEM, DMAI,
etc.) for which a build is compulsory to begin application development. These components must first be
cleaned and then rebuilt by the user before the user attempts to rebuild anything else. To do this, simply run
After that, each of the build targets listed by 'make help' can then be executed using:
In order to install the resulting binaries on your target, execute one of the "install" targets. Where the binaries
are copied is controlled by the EXEC_DIR variable in ${EZSDK}/Rules.make. This variable is set up to
point to your NFS mounted target file system when you executed the EZ SDK setup (setup.sh) script, but
can be manually changed to fit your needs.
You can remove all components generated files at any time using:
You can then install all the resulting target files using:
1. If you haven't already done so, follow the instructions in #Setting_up_the_EZ_SDK to setup your build
environment.
2. Recompile the kernel provided with the EZSDK by executing the following:
host $ cd ${EZSDK}
host $ make linux_clean
host $ make linux
host $ make linux_install
3. You will need a way for the boot loader (u-boot) to be able to reach your new uImage. TFTP server has
been setup in the #Setting_up_the_EZ_SDK section.
4. Copy your new uImage from the EXEC_DIR specified in the file ${EZSDK}/Rules.make to the tftpserver:
5. Copy the exported Linux kernel modules from the EXEC_DIR to the /lib/modules directory:
6. Run the u-boot script and follow the instructions. Select TFTP as your Linux kernel location and the file
'uImage' as your kernel image.
Note! In this release of the EZ SDK, U-Boot does not read the MAC Address from eFuses. As a result the
ethernet MAC Address needs to be set manually by choosing a valid random MAC Address. More details are
available in the PSP U-Boot documentation. Please run the following command to set the ethernet MAC
Address
7. Note that when you change your kernel, it is important to rebuild the kernel modules supplied by the
EZSDK sub-components. You can find a list of these modules under the directory
/lib/modules/2.6.32-rc2-davinci1/kernel/drivers/dsp/ (replace 2.6.32-rc2-davinci1 with the version of the
kernel applicable to your platform)
host $ ls ${HOME}/targetfs/lib/modules/2.6.32-rc2-davinci1/kernel/drivers/dsp/
For each module that you see listed, you should go back to the host, rebuild it, and replace the file with the
one from your EXEC_DIR. E.g. for cmemk.ko
host $ cd ${EZSDK}
host $ make cmem_clean
host $ make cmem
host $ make cmem_install
host $ sudo mv ${HOME}/targetfs/lib/modules/2.6.32-rc2-davinci1/kernel/drivers/dsp/cmemk.ko \
${HOME}/targetfs/lib/modules/2.6.32-rc2-davinci1/kernel/drivers/dsp/cmemk.ko.orig
host $ sudo cp ${HOME}/targetfs/home/root/dm816x-evm/cmem/cmemk.ko \
${HOME}/targetfs/lib/modules/2.6.32-rc2-davinci1/kernel/drivers/dsp
8. After updating all modules, start minicom or Tera Term and power-cycle the board. The new kernel will
now be loaded over TFTP from your Linux host.
1. Download Tera Term from this location, and start the application.
Port: COM1
Baud rate: 115200
Data: 8 bits
Parity: none
Stop: 1 bit
Flow control: none
NOTE: Kernel Bootargs can be generated by running the setup script. See the section
host $ dmesg
[14365.272631] sd 6:0:0:1: [sdb] 3862528 512-byte logical blocks: (1.97 GB/1.84 GiB)
[14365.310602] sd 6:0:0:1: [sdb] Assuming drive cache: write through
[14365.325542] sd 6:0:0:1: [sdb] Assuming drive cache: write through
[14365.325571] sdb: sdb1 sdb2
Wait for script to complete. On successful completion, remove the SD card from the host PC.
Note! If you want to recreate the full SD card with a separate partition for the EZSDK installer and the CCSv5
installer execute the following:
This takes significant extra time so it's not part of the default instructions.
The linux logo appears by default when the u-boot stages are being loaded. After the linux logo, one can give
the commands to load an image using the tftp and display the image at the u-boot command prompt.
2. Add the commands to display the bmp image at the u-boot to environment variable "bootcmd" and save the
environment to NAND (Note: NAND should be enabled).
u-boot :> setenv bootcmd 'tftp 0x81000000 ti_logo.bmp; bmp display 0x81000000; $bootcmd'
The logo would appear for around 15 seconds by default. To change the time for which the logo is displayed,
change the value of environment variable logotime at the u-boot but it should not be greater than 15. Save the
environment to NAND to see the change in time for which the logo is displayed during the next boot.
Note: By default, if the environment variable "logotime" is not defined in u-boot environment, it uses the
default value of 15 to display the logo for that much time.
Note! You need ensure that the EVM is connected to the Host via RS-232. You also need to ensure that the
NAND is available and turned on.
Please refer the U-boot documentation under the board-support folder in your EZ SDK installation for the
procedure required for copying boot loaders (MLO and u-boot) on NAND flash.
target # cd /usr/share/ti/ti-media-controller-utils
target # ./change_resolution.sh 720p60
Note! If you want to change the video resolution, then you must edit the OMTB script or call the necessary
OMX API. For more information please refer the OMTB and OMX documentation. You must make sure that
both the Graphics and Video resolution is configured to the same value.
target # cd /usr/share/ti/ti-media-controller-utils
target # cp load-hd-v4l2-firmware.sh /etc/init.d/load-hd-firmware.sh
target # sync
Now power cycle the board and it will be setup to load the alternate firmware which supports V4L2.