Introduction to C6Flo 1.0
From Texas Instruments Embedded Processors Wiki
This article is part of a series describing the C6Flo graphical development tool. Click the link above to return to the main page.
C6Flo is a free graphical development tool for TI's C6000 DSP family. This article defines graphical development as the process of designing and implementing a working DSP system without manually writing code, which appeals to people for different reasons. Inexperienced or non-specialized programmers can use this process to create a complete system and use the result as-is. This enables them to efficiently utilize highly specialized hardware, such as TI's C6000 DSPs, without investing time to develop the necessary expertise. They can make use of specialized, efficient algorithms and peripheral driver code that is enabled for graphical development by more advanced users.
Advanced users can also benefit from graphical development. A graphical tool can provide an easy starting point for new applications by automating the complex and often tedious "first steps" of application development. Creating a basically functional, reasonably efficient prototype in a few minutes can save hours of development time. Of course, this is only true if the graphical tool produces clear code that is easily modified or expanded.
C6Flo is designed with both classes of user in mind: basic users who want to implement their entire system graphically and advanced users who want to tweak and refine their system for maximum performance. C6Flo allows users to draw their DSP system graphically as a simple block diagram. C6Flo comes with over 70 blocks representing common DSP algorithms and peripheral I/O for recent DSP devices, and new blocks can be created and seamlessly integrated by anyone. C6Run parses block diagrams to create complete C-language applications, which can then be built and run through TI's Code Composer Studio (CCS) software. The following sections explain each step of this process in greater detail.
The following software must be installed on your development PC prior to using C6Flo:
- C6Flo Graphical Development Tool
- Code Composer Studio (v3.3 or v4)
- DSP/BIOS v5.41
- C6000 CodeGen Tools (v6.1.9 or higher)
- XDC Tools (v3.20 or higher)
- Microsoft .NET Framework (2.0 or higher)
Note: if using CCS4, you should be able to obtain up-to-date codegen tools using the built-in update feature.
Note: if using CCS4, you may still need to update your XDC Tools manually to version 3.20.xx.
Note: C6Flo currently works only on 32-bit Windows.
In addition to installing the above components, the following environment variable settings must be applied. This should be done automatically by the various TI installers.
- C6FROOT - Set to installation folder of C6Flo (set by C6Flo installer)
- CGTROOT - Set to installation folder of C6000 codegen tools installation (set by C6Flo installer)
- XDCPATH - Add path to "Blocks" folder within C6Flo installation (set by C6Flo installer) (path must use forward slashes, not back slashes)
- XDCROOT - Set to installation folder of XDC tools (set by XDC installer)
- BIOS_INSTALL_DIR - Set to installation folder of DSP/BIOS (set by DSP/BIOS installer)
After installing C6Flo and all of the required software components, you can check that these environment variables are set correctly in the "Advanced" tab of the Control Panel->System Properties screen. The following values are typical:
C6FROOT=C:\Program Files\Texas Instruments\C6Flo_1.02 CGTROOT=C:\Program Files\Texas Instruments\C6000 Code Generation Tools 6.1.16 XDCPATH=(pre-existing paths);C:\Program Files\Texas Instruments\C6Flo_1.02\Blocks XDCROOT=C:\Program Files\Texas Instruments\xdctools_3_20_00_41 BIOS_INSTALL_DIR=C:\Program Files\Texas Instruments\bios_5_41_02_14
Once your prerequisites are met and C6Flo is installed, run c6flo.exe in the C6Flo installation directory. You should see something similar to the following screenshot:
Note: If you don't see the block palette on the left side of the screen, enable it using The View->Components Window command.
Opening the Example Systems
The C6Flo installation includes multiple example systems that you can use as a starting point for your own work. To find them, use the File->Open command and navigate to the "Examples" folder in your C6Flo installation. The full path will typically look like this:
C:\Program Files\Texas Instruments\C6Flo_1.02\Examples
C6Flo opens files with the *.pfw extension. The following table summarizes the example systems.
|Example Name||Example Description|
|C6747AudioFilter||Applies IIR filters to stereo audio using optimized functions from the C674 DSPLIB. Separate filters are applied to the right and left audio channels. UART host control is also enabled to control the gain blocks, which basically serve as volume control at run time.|
|C6748VideoMux||Applies two algorithms from the C64+ IMGLIB--Sobel edge detection and median filtering--to live video. UART host control is enabled to control the mux block, selecting which video stream is output to the VIDEO OUT connector.|
|C6748AvSkeleton||Audio and video system that performs no extra processing. However, the "dummy" blocks insert convenient placeholder functions in the generated application. It's easy to add custom processing code in the C language domain after code generation; just look for the "dummy" proc functions in *_blocks.c.|
Drawing a New System
The example systems are a useful starting point, but you will eventually want to create your own system from scratch. Use the File->New command to start with a blank system diagram. The first thing you need to do is add a framework block to your system. Framework blocks represent the global configuration of your system: buffer sizes, memory segments, DSP/BIOS target names, etc. Navigate to the Framework category in the block palette, then use your mouse to drag a framework block from the palette into the gridded "Diagram" portion of the screen. A blue block with a small gear icon should appear in the diagram. Now you can do two things:
- Edit the parameters of the framework block
- Drag additional blocks into the diagram
The default parameters for the framework block are suitable for audio or generic DSP applications on the OMAP-L137 EVM. You can change them by left clicking the block, then editing the parameter pane that is located on the right side of the screen. This pane is used to configure whatever block is currently selected. You can edit the parameters of any block in the system at any time.
To add additional blocks, navigate between block categories in the palette and drag and drop blocks into the diagram. Normal processing blocks will be appear with one or more circles on their sides in the diagram. These circles represent input and/or output ports. Click on one port, then click on another to connect the two together. You can also click on intermediate points to route your connection lines cleanly through the diagram. Continue dragging, dropping, and connecting blocks until you have implemented a complete system. The following image shows what a system may look like when it's done.
Note: Input ports and output ports appear on the left and right side (respectively) of each block
There are a few simple rules to keep in mind when designing your system:
- Input ports must be connected to output ports, and vice versa
- Each port must connect to exactly one other port, i.e., no "open" ports are allowed; single connection only
- Output ports cannot be connected to input ports earlier in the system, i.e., no feedback connections
Generating the Application
Once you've finished drawing your system in the block diagram view, you're ready to create your application code. Simply use the File->Generate Code command to begin the code generation process. You will be prompted to save your block diagram if you haven't already, and then messages will begin to appear in the lower left side of the screen. A successful code generation process should look something like this:
Note: Error messages will appear here if your prerequisites are not met.
Assuming you don't see any error messages, your application is now complete! You're now ready to open it in Code Composer Studio to build, load, and run it on your DSP. Depending on which version of Code Composer Studio you are using, you need to open your application in slightly different ways. For CCS3.3, you can simply open the generated PJT file. For CCS4, you need to use the Import Legacy CCSv3.3 Project wizard in the Project menu to achieve the same result.
Controlling the Application at Run Time
While you can assign static parameters to your system and blocks in the diagram view, you will also want to adjust certain key parameters at run time. For instance, you may want to adjust the volume of an audio system in real time, or select another channel with a multiplexer block. C6Flo provides a powerful and flexible host control protocol to accommodate these requirements.
To enable host control, you need another special, standalone block in addition to the framework block. This host control block creates a new thread in your application that listens for instructions from an external host at run time. That host could be a PC communicating via UART, some remote device communicating via EMAC, or even an ARM core communicating via DSPLINK. The communication channel depends on the specific host control block that you use.
Host control is an "opt in" design decision for each block. The only configuration that is possible is what the block author specifically enables via its control function. Also, blocks must be explicitly enabled for host control in the diagram view by setting their c6flo_id parameter to a unique, non-zero value. In this way, unintended host interactions are prevented at run time.
Understanding the Application
Now that you've created your application, you're ready to build, load, and run it in Code Composer Studio. If that's all that you want to do, then you're already done. If you want to understand and modify the application source code, keep reading. This section describes the contents and structure of your application.
Note: <app> is set to the name of the framework block in your diagram
The above image lays out the general structure of your application. It's a simple C-language application with three source files, one header file, a DSP/BIOS configuration file (TCF), and a CCS3.3 PJT file. The purpose and contents of each file are described in the following table.
|File Name||File Contents|
|<app>_main.c||Application main function and some common utility code. The main function dynamically creates one DSP/BIOS TSK for each thread in the application (including the host control thread if present).|
|<app>_threads.c||Loop functions for processing and host control threads. Each of these functions comprises a DSP/BIOS TSK that is created dynamically in the main function. These functions call the block functions in sequence to implement the processing chain(s) that you draw in the diagram view.|
|<app>_blocks.c||Block instance structs and functions. Each block is represented by four functions: create, initialize, process, and control. These functions are reused when possible, i.e., between separate instances of the same block type.|
|<app>.h||Standard includes, typedefs and macros; block typedefs and function prototypes.|
|<app>.tcf||DSP/BIOS configuration text. Most of the framework block configuration parameters are reflected here. This file can be viewed graphically, using the built-in tool in Code Composer Studio, or as plain text.|
|<app>.pjt||CCS3.3 project definition.|
The TCF file contains some critical global configuration parameters, but the most interesting files are probably two of the C source files: <app>_threads.c and <app>_blocks.c. These files implement the processing threads from your graphical diagram as well as each individual block in that diagram. If you look at a thread function, you will see the following sequence of events:
- Declare buffer pointers and assign to arrays (one input and one output array for each block in the thread)
- Allocate buffers using C6Flo API
- Call create function for each block
- Outer loop: Call initialize function for each block
- Inner Loop: Call process function for each block
- Free buffers (should never come here)
The loop structure is simple. Ordinarily, the application will call each create function once, then call each initialize function once. It will then call each process function in sequence repeatedly. Only if a block determines that it needs to "reset" will execution "fall" to the outer loop again. Also, execution will never fall from the outer loop unless the thread aborts on some error condition.
Another thing you may notice is that only three of the four standard block functions are called by the thread; the control function is missing. This is because the control function is only called in response to host control events, if host control is enabled in your application; it is not called during normal processing.
Note: C6Flo automatically divides your diagram into threads during the code generation process
You can review or edit the implementation of each block function in the <app>_blocks.c source file. You'll find an instance struct for each block near the top of the file. These contain the parameters you entered in the diagram view, and you can manually alter their values in this source file. Below the structs, you will find four sets of functions: the create functions for each block, the initialize functions, the process functions, and the control functions. Editing these functions changes the behavior of the blocks in your system. Be careful, though: changing one function can alter more than one block, since multiple instances of the same block type often share functions.
A new C6Flo installation includes over 70 blocks provided by TI, which are summarized in the following table.
|Frameworks||4||C6747, C6748, DM6437, DM648|
|C6747 EVM||3||Audio, UART host|
|C6748 EVM||5||Audio, Video, UART host|
|DM6437 EVM||5||Audio, Video, UART host|
|DM648 EVM||5||Audio, Video, UART host|
|C674 DSP Lib||6||FFT, filters, autocor|
|FIL Filter Library||7||DF2 biquads, 256-tap FIR|
|C67 Fast RTS Lib||15||100%|
|C64+ DSP Lib||6||FFT, filters, autocor|
|C64+ IMG Lib||7||convolution, Sobel, median, thresholding|
|C64+ IQMath Lib||15||100%|
|Total||109||Current as of v1.02|
These blocks are described in greater tale on a separate wiki page.