Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

C6Run FAQ

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.

C6Run FAQ

This page contains frequently asked questions (FAQs) about the C6Run project and it's usage and the corresponding answers to those questions.


C6Run General Questions

Why do I need C6Run?

You need C6Run if you are an ARM Linux developer and you want to easily get started running arbitrary DSP code. A typical use case will be to benchmark an algorithm on the DSP.

This project should be of particular interest to ARM developers who are familiar with building applications for the Linux OS using the command-line ARM GCC cross-compiler and who want a similar mechanism to build and run code on the DSP.

What Does C6Run Do?

The C6Run project allows you to seamlessly use the DSP on ARM+DSP devices from the ARM, without having to deal with any advanced, and potentially complicated, frameworks and software stacks. C6Run is a set of tools which will take in C files and generate either an ARM executable, or an ARM library which will leverage the DSP to execute the C code.

What Devices Does C6Run Support?

The C6Run project targets two-core heterogeneous SoC processors from Texas Instruments, specifically ARM+DSP devices which run Linux on the ARM. The complete up-to-date list can be found here.

What software development environments can C6Run be used in?

The C6Run tool can fit into three primary software development situations

  1. As a stand-alone product. Simply download the C6Run source package and follow the system setup instructions. For full system development, you will need a Linux kernel source tree port for you platforms, a u-boot source tree port for your platform, and a target filesystem for your platform.
  2. Inside of a TI SDK. C6Run is included as part of official SDK4 releases from Texas Instruments. It can also potentially be used in older SDKs (e.g., like the DM6467T in the DVSDK v3.10).
  3. As part of the community Angstrom distribution for platforms such as beagleboard and hawkboard.

Can I use C++ with C6Run?

With C6RunApp, C++ usage is only restricted by the TI compiler's support for C++. With C6RunLib, any source files that are used to generate the static library of DSP-executing code must be pure C files. The resulting library can be linked with ARM C++ code, as long as the declarations of the functions encapsulated in the generated library are defined as C functions. The suggested way to do this can be found here.

What is in the backend DSP-side library for a platform?

The backend DSP-side libraries (which are created when you follow the system setup steps) are built as follows:

  1. The DSP/BIOS configuration is performed, using the configuration provided in the DSPlink package for the specified platform. Source files and a linker command file are generated by this step.
  2. The replacement BIOS entry and exit points are built (replaces the part of BIOS that calls main() with one that calls _C6Run_main and replaces the part of BIOS that exits the application)
  3. C6Run task program is built. This program creates a single BIOS task which for C6RunApp calls the user-supplied main() function or for C6RunLib calls the remote procedure call dispatch loop.
  4. IPC code is built. This code provides the interface between the ARM and DSP cores and make use of DSPLink APIs.
  5. Standard C I/O replacement code is built. These provide a new low-level implementation of a few functions of the DSP RTS lib so that C I/O calls are mapped back to the ARM via DSPLink.
  6. The DSPLink DSP-side libraries are extracted so that all the object files from those libraries are available in a temporary local location.
  7. All the above object files are archived to create the C6Run dsp-side library. Debug and release versions are built.

What is in the backend ARM-side library for a platform?

The backend ARM-side libraries (which are generated with the 'make build' step in the Getting Started section) are built as follows:

  1. IPC code is built. This code provides the interface betweeen the ARM and DSP cores and make use of DSPLink APIs.
  2. C6Run top-level code is built. This provides setup and tear-down mechanisms for the C6Run framework. Uses the IPC code. Also includes a CIO server thread for receiving and processing CIO requests from the DSP.
  3. Dipatch routines for RPC function calls are built (these only get used for C6RunLib builds).
  4. User-space CMEM and GPP-side DSPLink libraries are extracted to temporary local locations for inclusion in the final GPP-side library.
  5. All the above object files are archived into C6Run gpp-side library. Debug and release versions are built.

How do I change the memory map for a platform?

The memory map for a particular platform can be altered at configuration time through command-line options, or by editing the platforms.mak file for the platform. The variables of interest are:

  • DSP_REGION_BASE_ADDR = starting address of region that C6Run uses
  • DSP_REGION_CMEM_SIZE = size of region given to heap for allocating buffers that the DSP and ARM can share
  • DSP_REGION_CODE_SIZE = size of region given to DSP for executable code, its stack, heaps, etc.

See the system setup steps for an example on how to change the memory map at configure time. If no overriding variables are provided on the command-line, then the default values from the platform.mak file are used.

How do I create/modify a platform?

The easiest way to create a platform specific for your system is to start with an existing platform of the same SoC type and copy all files in that platform directory to a new directory in the platforms path (let's call it myplatfrom - so there would now be a directory platforms/myplatform with files copied from an existing platform).

Now you can go back to the Getting Started steps and start over using 'make myplatform_config', then 'make build'.

C6RunLib Questions

What can I do with C6RunLib?

Once you are happy with the benchmark of my algorithm on DSP, you can use RunLib to generate an ARM library that can be used in your ARM application to offload the algorithm to the DSP for acceleration and/or to free up ARM.

Can I use C6RunLib in a system that includes codec engine codecs (eg video/image/audio)?

No. C6RunLib uses DSP/Link internally and so is mutually exclusive to codec engine based codecs. To integrate an algorithm within codec engine you need to use C6Accel functions or write your own iUniversal algorithm.

How does the C6RunLib tool actually work?

The C6RunLib project does the following to build a library that will run on the DSP:

  1. The c6runlib-cc tool performs a number of steps on the supplied C source files:
    1. Uses the TI code generation tool to create a DSP object file from the C source.
    2. Uses GCC to parse the C files and generate intermediate data (called a translation unit). The translation unit data is analyzed by a Perl script and then used to generate ARM-side C code which act as a stub on the ARM to resolve the function symbols and dispatch the call to the DSP. This C code is compiled to an object file using the ARM GCC cross compiler.
    3. The same perl script used to generate the stub C code also creates a textfile with a list of all functions being compiled to run on the DSP.
  2. When the c6runlib-ar archiver tool is called a number of steps are taken:
    1. The DSP tools are used to link the input DSP object files (generated by c6runlib-cc) against a pre-built, DSP-side C6Run library. The result is the complete DSP-side executable image in standard TI COFF format.
    2. The DSP executable image size is minimized by using the symbol stripping tool, strip6x.
    3. The contents of the stripped DSP executable file are converted to a C byte array in a temporary C header file. This header file is referenced by the main ARM-side C6Run loader.
    4. The main C6Run object file is built using the ARM cross compiler tools, including the DSP-side executable inside of it.
    5. The final DSP executable is analyzed and the address of all library functions (from the original C files processed by c6runlib-cc) are extracted and used to create ARM assembly files containing absolute symbol references. These assembly files are assembled to object files using the ARM GCC assembler.
    6. The ARM stub object files, the symbol reference object files, the C6Run ARM-side backend library, and the main C6Run object file are all combined into a single library file, with the name of the library file specified on the c6runlib-ar command-line.

The output of the above steps is an ARM library file, which contains inside of it the entirety of the image that will get loaded to the DSP. That DSP image contains the compiled source provided by the user on the c6runlib-cc command line. An application that wishes to call these library functions on the DSP should link against this library.

Every time an application calls one these library functions, the following takes place:

  1. The ARM-side function stub is entered and a check is made to see if the C6Run framework has been initialized.
  2. If the framework has not been initialized (if this is the first library function call), the following takes place:
    1. Initialize CMEM if not already initialized, create a CMEM buffer of the size of the DSP executable image, copy the DSP executable data from the ARM process memory to the CMEM buffer.
    2. DSPLink is initialized (PROC_setup, PROC_attach, POOL setup, MSGQ setup).
    3. The DSP executable is loaded to the DSP (PROC_load) using the CMEM buffer (PROC_load requires contiguous physical memory address provided by CMEM).
    4. DSP starts running (PROC_start).
    5. CMEM buffer is freed since it is no longer needed.
    6. Interprocessor communication (IPC) is setup using Message Queues.
    7. A server thread is spawned for receiving and processing all CIO requests.
    8. The main ARM thread blocks waiting for an READY message from the DSP via the CONTROL message queue. The READY message indicates that the DSP has been correctly loaded and is waiting to receive remote procedure call requests. The CIO thread loops waiting for communication from the DSP via the CIO message queue, and then handling all C I/O operations requested by the DSP.
  3. The function arguments are marshalled into a message buffer for transmission to the DSP.
  4. Any required cache operations for buffer arguments are handled (DSP input buffers must be written back on the ARM side).
  5. The function call message is sent to the DSP and the DSP unmarshalls the parameters, performs invalidate operations on buffer input arguments, and then calls the function with the arguments.
  6. The return value from the function (if there is one) is marshalled into a message for return to the ARM. Any output buffers have their results written back from the DSP cache. The function call return message is sent to the ARM.
  7. On the ARM side, any DSP output buffers are invalidated. The function return value is returned back to the calling application.
  8. When the ARM application terminates, the C6Run exit and cleanup takes place automatically (registered via the atexit() function).

Can I use TI optimized libraries with C6RunLib?

Absolutely yes. To do this you can provide any compatible object files or library files on the command-line to the c6runlib-ar utility. The c6runlib-ar archiver tool will identify that these object files or libraries were not created using c6runlib-cc, but will still link them into the DSP executable image. Therefore your code can reference functions and variables that are found in these other object sources.

For example, you may have a file1.c, file2.c, and file3.c. If each of these files references a function from TI's optimized DSPLib library, you could compile them this way:

  c6runlib-cc -c -I/opt/dsplibs/c64plus-dsplib_2_02_00_00/ file1.c file2.c file3.c

Note that you must provide the header file search path using the -I option. Then the library can be created as follows, with the library specified as an object source:

  c6runlib-ar rcs file1.o file2.o file3.o /opt/dsplibs/c64plus-dsplib_2_02_00_00/lib/dsplib64plus.lib 


C6RunApp Questions

What can I do with C6RunApp?

A typical use case is to benchmark your algorithm on the DSP to see how it can benefit from moving from ARM to DSP

How does the C6RunApp tool actually work?

The C6RunApp project does the following to build an executable program that will run on the DSP:

  1. The DSP tools are used to build the supplied source and link it against a pre-built, DSP-side C6Run library. The result is the complete DSP-side executable image in standard TI COFF format.
  2. The DSP executable image size is minimized by using the symbol stripping tool, strip6x.
  3. The contents of the stripped DSP executable file are converted to a C byte array in a temporary C header file. This header file is referenced by the main ARM-side C6Run loader.
  4. The C6Run loader program is built using the ARM cross compiler tools, including the DSP-side executable inside of the binary ARM ELF executable. This ARM executable is the same name as specified on the command line of the C6RunApp cross-compiler script.

The output of the above steps is an ARM Linux executable, which contains inside of it the entirety of the image that will get loaded to the DSP. That DSP image contains the compiled source provided by the user on the c6runapp-cc command line

When this ARM executable is run, the following takes place:

  1. The ARM loader begins by initializing the C6Run framework. This consists of the following:
    1. Initialize CMEM, create a CMEM buffer of the size of the DSP executable image, copy the DSP executable data from the ARM process memory to the CMEM buffer.
    2. DSPLink is intialized (PROC_setup, PROC_attach, POOL setup, MSGQ setup).
    3. The DSP executable is loaded to the DSP (PROC_load) using the CMEM buffer (PROC_load requires contiguous physical memory address provided by CMEM).
    4. DSP starts running (PROC_start).
    5. CMEM buffer is freed since it is no longer needed.
    6. Interprocessor communication (IPC) is setup using Message Queues.
    7. A server thread is spawned for receiving and processing all CIO requests.
  2. The main ARM thread blocks waiting for an EXIT message from the DSP via the CONTROL message queue. The CIO thread loops waiting for communication from the DSP via the CIO message queue, and then handling all C I/O operations requested by the DSP.
  3. When the main ARM thread recieves the EXIT message (indicating the user code is complete either via a return from main() or via the exit() function), the ARM performs teardown on the DSPLink setup, cleanly shutting down the DSP.

Can I use TI optimized libraries with C6RunApp?

Absolutely yes. To do this you can provide any compatible object files or library files on the command-line to the c6runapp-cc utility when doing the linking step. The c6runapp-cc tool will link them into the DSP executable image. Therefore your code can reference functions and variables that are found in these other object sources.

For example, you may have files main.c, file1.c, and file2.c. The file1.c and file2.c files reference one or more functions from TI's optimized DSPLib library, you could compile them this way:

  c6runapp-cc -c -I/opt/dsplibs/c64plus-dsplib_2_02_00_00/ main.c file1.c file2.c

Note that you must provide the header file search path using the -I option. Then the application can be created as follows, with the library specified as an object source:

  c6runapp-cc -o app.out main.o file1.o file2.o /opt/dsplibs/c64plus-dsplib_2_02_00_00/lib/dsplib64plus.lib 

Note that we do not use the -l<library> syntax which is typical under Linux, as there are no conventions in the DSP world for naming and placing libraries (using -l<library> syntax requires a file called lib<library>.a or lib<library>.so to exist in the standard library search paths).

Return to C6Run 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.