Getting Started With C6EZRun

From Texas Instruments Wiki
Jump to: navigation, search

END OF LIFE

C6Run is still available for download, but is no longer being actively developed or maintained. Please consider other alternatives such as, Codec Engine IUNIVERSAL support, OpenCL or RCM.

^ Up to main C6EZRun Main Page ^

This article is part of a collection of articles describing the C6EZRun Software Development Project. Select the link above to return to the main project page.

Getting Started With C6EZRun

This page gives information on how you can get started using C6EZRun.


Where do I get the C6EZRun package?

There are several ways to get the C6EZRun software, each of which is detailed in this section.

TI Software Development Kit (SDK) Download

The official TI DVSDK v4.xx and EZSDK v5.xx for ARM+DSP devices includes the C6EZRun package. The DVSDK v4.xx downloads are available here and the EZSDK v5.xx downloads are available here. If you are developing on an officially supported TI EVM platform, this is the recommended way to use the C6EZRun tools. You should refer to SDK documentation for steps related to C6EZRun. If you want to upgrade the C6EZRun version in the SDK, refer to the directions below.

Stand-alone Download

The latest packaged, stand-alone release is available from the TI website. Packaged source releases are also available from the file release section of the GForge site. There is no difference between the packages hosted on the two sites.

Direct Source Repository Access

  • The C6EZRun project is an open source project hosted on TI's external GForge server, gforge.ti.com. It is licensed under the standard three-clause BSD License. The official development project page is here.
  • For developers, subversion access (using a subversion (SVN) client) to the development trunk is available at https://gforge.ti.com/svn/dspeasy/trunk.
      [host]$ svn checkout --username anonymous https://gforge.ti.com/svn/dspeasy/trunk
    Note that the current trunk may not represent a stable version of the project. For SVN access to stable releases, you should checkout from a tags path.
      [host]$ svn checkout --username anonymous https://gforge.ti.com/svn/dspeasy/tags/<MM>_<mm>_<pn>_<bn>
    <MM>_<mm>_<pn>_<bn> is the release's particular version number (MM=major, mm=minor, pn=patch number, bn=build number).


What other software do I need to get going?

The build system has several dependencies, which can be satisfied in various ways, depending on your development environment. You should refer to the appropriate section below for the scenario that most appropriately corresponds to you.

TI SDK Dependencies

When C6EZRun is found inside an official TI SDK product, the dependent components are all provided, with the possible exception of the compiler tools. You should refer to the SDK setup guide for information on how to get and configure and SDK dependencies.

When operating inside a Texas Instruments' SDK the kernel modules should have been built with their related dependent components, and therefore should already be present.

Stand-alone Dependencies

When used as a stand-alone product, the top-level makefile in the package can be used to automatically retrieve all required components (see below). The C6EZRun package, as of version 0.97, supports two different underlying inter-processor software layers: DSPLink and SysLink. The software dependencies vary depending on which is in use and are given in the tables below.

Table of Software Dependencies when using DSPLink IPC
Dependency
DSP/BIOS 5 real-time operating system
DSPLink
XDCtools Package
Linux Utils Package
Local Power Manager (LPM) for Linux (FOR OMAP3 PLATFORMS ONLY)


Table of Software Dependencies when using SysLink IPC
Dependency
SysBios 6.3x real-time operating system
SysLink
IPC 1.x for SysBios
XDCtools Package
Linux Utils Package


The C6EZRun tools also require the proprietary C6000 Code Generation Tools from Texas Instruments and a GCC cross compiler for the ARM architecture. These tools may be required to be downloaded separately by the user depending on their development environment. Links are given in the table below.

Table of Compiler Dependencies
Dependency Version Direct Download Link
TI C6000 Codegen Tools v7.0.x, v7.2.2 or higher (v7.2.0 and v7.2.1 are not compatible) Requires my.ti.com login to access.
ARM Cross Compiler tools. Older targets may also require the Montavista GCC cross-compiler tools, as delivered in SDKs and/or LSPs from TI. 2009q1 (later versions may work) Link to CodeSourcey G++ Lite


Additonally, in the the stand-alone use case, you will need a built kernel source tree to build the needed kernel modules. The location of this is platform dependent, as are the instructions to build it. To build the kernel (the uImage), you will also need the mkimage tool from a built u-boot tree.

Angstrom/OpenEmbedded Dependencies

When C6EZRun is built as part of a distribution, such as Angstrom, all required dependent components are satisfied by the OpenEmbedded recipes.

The kernel modules should have been built with their related dependent components, and therefore should already be present.


How do I setup the C6EZRun tools?

There are quite a few different setup and usage scenarios for the the C6EZRun tool. Right now, the main ways you will use C6EZRun will be by using it inside an official TI SDK product, or by downloading and configuring it directly (the stand-alone use case). Instructions for these two scenarios are given below. A third usage scenario is within the Angstrom distribution, where an OpenEmbedded recipe can be used to build and use the C6EZRun tools.

Important Note about Memory Map when using DSPLink

If you setup a custom memory map for the DSP, you should be aware of some limitations. The DSP_REGION_CODE_SIZE must be greater than or equal to 3MB (0x00300000). This is because the CODE_SIZE region contains 1 MB of shared memory used by DSPLink and half of the total size is also given to the DSP's local heap. So for 3MB, 1.5MB would be given to heap memory, 1 MB would be given to DSPLink share memory, and approximately 0.5MB would be available for actual user code/data.

The DSP_REGION_CMEM_SIZE can be made any size, but it should be a multiple of 1MB. The DSP_REGION_BASE_ADDR should also be aligned to a 1MB address in the physical memory map. These two restrictions will cause the CODE region to also be aligned to 1MB, which is a requirement of DSPLink.

TI DVSDK v4.xx Setup

To integrate the latest C6EZRun package into the official Texas Instruments DVSDK v4.xx, follow the directions below.

  • Copy the C6EZRun download package into the top-level install path of the SDK (called <DVSDK_INSTALL_DIR>).
      [host]$ cp C6Run_<MM>_<mm>_<pn>_<bn>.tar.gz  <DVSDK_INSTALL_DIR>/
  • Enter into the DVSDK top-level install path.
      [host]$ cd <DVSDK_INSTALL_DIR>/
  • Un-tar the C6EZRun install package inside the DVSDK.
      [host]$ tar -xvzf C6Run_<MM>_<mm>_<pn>_<bn>.tar.gz
  • Edit the DVSDK Rules.make file and change the C6RUN_INSTALL_DIR variable.
    C6RUN_INSTALL_DIR=$(DVSDK_INSTALL_DIR)/C6Run_<MM>_<mm>_<pn>_<bn>
    IMPORTANT NOTE: You may also need to update the top-level Makefile to make sure the C6EZRun configured memory map matches the SDK's default memory map. For example, for the OMAP3530/DM3730 DVSDK v4.01.00.09, the following changes must be made to the config line in the 'c6run' target of the SDK top-level Makefile.
Before After
c6run:
  $(MAKE) -C $(C6RUN_INSTALL_DIR) \
  CODEGEN_INSTALL_DIR="$(CODEGEN_INSTALL_DIR)" \
  BIOS_INSTALL_DIR="$(BIOS_INSTALL_DIR)" \
  XDC_INSTALL_DIR="$(XDC_INSTALL_DIR)" \
  LINK_INSTALL_DIR="$(LINK_INSTALL_DIR)" \
  CMEM_INSTALL_DIR="$(CMEM_INSTALL_DIR)" \
  LPM_INSTALL_DIR="$(LPM_INSTALL_DIR)" \
  ARM_TOOLCHAIN_PATH="$(CSTOOL_DIR)" \
  ARM_TOOLCHAIN_PREFIX="arm-none-linux-gnueabi-" \
  dm3730_config
c6run:
  $(MAKE) -C $(C6RUN_INSTALL_DIR) \
  CODEGEN_INSTALL_DIR="$(CODEGEN_INSTALL_DIR)" \
  BIOS_INSTALL_DIR="$(BIOS_INSTALL_DIR)" \
  XDC_INSTALL_DIR="$(XDC_INSTALL_DIR)" \
  LINK_INSTALL_DIR="$(LINK_INSTALL_DIR)" \
  CMEM_INSTALL_DIR="$(CMEM_INSTALL_DIR)" \
  LPM_INSTALL_DIR="$(LPM_INSTALL_DIR)" \
  ARM_TOOLCHAIN_PATH="$(CSTOOL_DIR)" \
  ARM_TOOLCHAIN_PREFIX="arm-none-linux-gnueabi-" \
  DSP_REGION_BASE_ADDR=0x83700000 \
  DSP_REGION_CMEM_SIZE=0x02900000 \
  DSP_REGION_CODE_SIZE=0x02000000 \
  dm3730_config
  • Run the make command to build the new C6EZRun package.
      [host]$ make c6run
  • Run the following
      [host]$ source C6Run_<MM>_<mm>_<pn>_<bn>/c6run_environment.sh
    (Note that in releases prior to v0.98, the environment file was named simply 'environment.sh') This will put all required variables into the current environment based on the configuration provided at build time. If you exit your terminal window and then open a new one, you will need to re-run this command to get these environment variables back (they aren't permanent). You can now build the tests and examples in the C6EZRun package. You can use the Makefiles provided with these tests and examples as a template for your own projects.

Stand-alone Setup

The C6EZRun tools are intended to be used on a Linux host development system, in the same way that the GCC cross-compiler tools for ARM are run on a Linux host. If you plan to use the C6EZRun tool in a standalone environment (outside of an SDK or Angstrom/OE), follow the steps provided below.

  1. Un-tar the C6EZRun install package to some location on your host Linux system (note that <MM>_<mm>_<pn>_<bn> reflects the version number of the package).
      [host]$ tar -xvzf C6Run_<MM>_<mm>_<pn>_<bn>.tar.gz
  2. Enter into the top-level directory of the package
      [host]$ cd C6Run_<MM>_<mm>_<pn>_<bn>
  3. Get and install the required dependencies listed previously (except the compilers - these must be downloaded and installed manually). The easiest way to get these components is to use the 'make get_components' command. It uses the wget utility on your Linux host system to download and install the components in the C6Run top-level path. It should be run from within the C6Run_<MM>_<mm>_<pn>_<bn> directory. If you want to use any other versions of the dependent components, then you can edit the Rules.mak file to specify different version numbers before running this step.
      [host]$ make get_components
  4. Edit the Rules.mak file at the top-level of the package. Make sure all paths are correctly specified to point to the install location for the various dependencies given above. If you used the get_components target (above), most variables in this file are already correct.
  5. For your targeted platform, edit the platforms/<PLATFORM_NAME>/platform.mak file to reflect the location of the u-boot and linux kernel sources (needed for building any required Linux kernel modules). Generally speaking, you shouldn't need to edit anything further in this file.
  6. Configure for your desired platform (run 'make help' to see available platforms)
      [host]$ make <platform>_config
    If you wish to alter the physical memory that the C6EZRun software will use, you can provide the following variables when running the config step: DSP_REGION_BASE_ADDR=0xZZZZZZZZ, DSP_REGION_CMEM_SIZE=0xZZZZZZZZ, DSP_REGION_CODE_SIZE=0xZZZZZZZZ. For example, the following command will indicate that the DSP reqion begins at 0xC6000000, with the CMEM region being 16MB (0x01000000) in size, and the DSP code region also being 16MB (0x01000000). Then the total region in use by the C6Run framework will be from 0xC6000000 to 0xC8000000.
      [host]$ make DSP_REGION_BASE_ADDR=0xC6000000 DSP_REGION_CMEM_SIZE=0x01000000 DSP_REGION_CODE_SIZE=0x01000000 <platform>_config
  7. (OPTIONAL) If you do not have a built kernel tree, you can use the C6Run make system to build it (note that the kernel and uboot directories in platform.mak must be correct). A built kernel tree is required to build the kernel modules in the next step.
      [host]$ make linux
  8. From the top-level of the C6Run install location run 'make everything'.
      [host]$ make everything
    This may take some time and there will be a lot of output on the screen. If something goes wrong, you can build the following targets separately to get an idea of where the build failure originated:
    • Clean and build DSP-side back-end C6Run library:
        [host]$ make dsp_libs
    • Clean and build ARM-side back-end C6Run library:
        [host]$ make gpp_libs
    • Clean and build CMEM and DSPLink kernel modules:
        [host]$ make modules
  9. If you intend to build any of the included test cases or examples, you can do one of two things:
    • Add the <C6Run Install Path>/bin directory and the bin directory of the ARM cross-compiler tool to the system path. If not using the CodeSourcery ARM GCC tools, you will also need to specify the environment variable ARM_TOOLCHAIN_PREFIX to contain the correct GCC cross compiler prefix. The specifics of how to do this may vary from one Linux distribution to another. For Ubuntu, see here. For other systems, adding profile scripts to the directory /etc/profile.d or by creating/editing the ~/.bash_profile, ~/.bash_login, or ~/.profile files. The assumption is that the user is using the typical BASH shell on their Linux host.
    • Run the following
        [host]$ source c6run_environment.sh
      (Note that in releases prior to v0.98, the environment file was named simply 'environment.sh') This will put all required variables into the current environment based on the configuration provided at build time. If you exit your terminal window and then open a new one, you will need to re-run this command to get these environment variables back (they aren't permanent).
  10. (OPTIONAL) Build the included example projects.
      [host]$ make examples
  11. (OPTIONAL) Build the included test cases.
      [host]$ make tests
  12. (OPTIONAL) Install the test cases, examples, and run-time scripts to a specified path (typically a shared target filesystem path).
      [host]$ make INSTALL_DIR=<desired install path> install_programs

Angstrom/OE Setup

Information on using C6EZRun with Angstrom for Beagleboard and Beagleboard-xM can be found here.


I built something, now how do I run it?

  1. Setup your platform for booting to Linux kernel using a root file system you provide (information on how to do this is beyond the scope of this project, but typically consists of getting u-boot loaded and running, configuring boot arguments for the Linux kernel under u-boot, and then initiating the kernel boot process from u-boot).
  2. IMPORTANT: You need to use the appropriate 'mem=' bootarg for the kernel, so that Linux kernel will not use the memory that the C6Run expects to use in the memory map. This information is shown when the make <platform>_config step is performed. The physical memory region that C6Run uses can be altered per the instructions given above.
  3. Copy the kernel modules (*.ko) and the module loading and unloading scripts (*.sh) to your target's filesystem from the C6Run/platforms/<platform> path.
  4. Copy any executables that you have built using the C6Run tools to your target's filesystem.
  5. Boot the system.
  6. Login, locate and run the loadmodules.sh script.
      [target]$ ./loadmodules.sh
  7. Run any one program that you have created with the C6Run tools. Only one program can use the DSP at a time.


Return to C6EZRun Main page

^ Up to main C6EZRun Main Page ^

This article is part of a collection of articles describing the C6EZRun Software Development Project. Select the link above to return to the main project page.