TMS320C6000 Code Composer Studio Tutorial Literature Number: SPRU301C February 2000 Printed on Recycled Paper
IMPORTANT NOTICE Texas Instruments and its subsidiaries (TI) reserves the right to make changes to their products or to discontinue any product or service without notice, and advises customers to obtain the latest version of relevant information to verify, before placing orders, that the information being relied on is current and complete.
This is a draft version printed from file: tut_pref.fm on 2/26/0 Preface Read This First About This Manual Code Composer Studio speeds and enhances the development process for programmers who create and test real-time, embedded signal processing applications. Code Composer Studio extends the capabilities of the Code Composer Integrated Development Environment (IDE) to include full awareness of the DSP target by the host and real-time analysis tools.
Notational Conventions Notational Conventions This document uses the following conventions: ❏ The TMS320C6000 core is also referred to as ’C6000. ❏ Code Composer Studio generates files with extensions of .s62 and .h62. These files can also be used with both the TMS320C6201 and the TMS320C6701. DSP/BIOS does not use the floating-point instructions that are supported by the TMS320C6701. ❏ Program listings, program examples, and interactive displays are shown in a special typeface.
Related Documentation from Texas Instruments Related Documentation from Texas Instruments The following books describe the devices, related support tools, and Code Composer Studio. Most of these documents are available in Adobe Acrobat format after you install Code Composer Studio. To open a document, from the Windows Start menu, choose Programs−>Code Composer Studio ’C6000−>Documentation.
Related Documentation ports, direct memory access (DMA), clocking and phase-locked loop (PLL), and the power-down modes. TMS320C62x Technical Brief (literature number SPRU197) gives an introduction to the digital signal processor, development tools, and third-party support. TMS320C6201 Digital Signal Processor Data Sheet (literature number SPRS051) describes the features of the TMS320C6201 and provides pinouts, electrical specifications, and timings for the device.
This is a draft version printed from file: tutorialtoc.fm on 2/26/0 Contents 1 Code Composer Studio Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1 This chapter provides an overview of the Code Composer Studio software development process, the components of Code Composer Studio, and the files and variables used by Code Composer Studio. 1.1 Code Composer Studio Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 3 Developing a DSP/BIOS Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 This chapter introduces DSP/BIOS and shows how to create, build, debug, and test programs that use DSP/BIOS. 3.1 Creating a Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 3.2 Adding DSP/BIOS Files to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 3.
Contents 6.6 6.7 7 Things to Try. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-12 Learning More . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-13 Connecting to I/O Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1 This chapter introduces RTDX and DSP/BIOS techniques for implementing I/O. 7.
x
Chapter 1 Code Composer Studio Overview This chapter provides an overview of the Code Composer Studio software development process, the components of Code Composer Studio, and the files and variables used by Code Composer Studio. Code Composer Studio speeds and enhances the development process for programmers who create and test real-time, embedded signal processing applications. It provides tools for configuring, building, debugging, tracing, and analyzing programs. Topic Page 1.
Code Composer Studio Development 1.1 Code Composer Studio Development Code Composer Studio extends the basic code generation tools with a set of debugging and real-time analysis capabilities. Code Composer Studio supports all phases of the development cycle shown here: Design Code & build Debug Analyze conceptual planning create project, write source code, configuration file syntax checking, probe points, logging, etc.
Code Composer Studio Development Code Composer Studio includes the following components: ❏ TMS320C6000 code generation tools: see section 1.2 ❏ Code Composer Studio Integrated Development Environment (IDE): see section 1.3 ❏ DSP/BIOS plug-ins and API: see section 1.4 ❏ RTDX plug-in, host interface, and API: see section 1.5 These components work together as shown here: Host Target C ode Com poser Stud io source file s .c db (C o n fig d a tab a s e ) c fg.c m d c fg.s 6 x c fg.
Code Generation Tools 1.2 Code Generation Tools The code generation tools provide the foundation for the development environment provided by Code Composer Studio. Figure 1–1 shows a typical software development flow. The most common software development path for C language programs is shaded. Other portions are peripheral functions that enhance the development process.
Code Generation Tools The following list describes the tools shown in Figure 1-1: ❏ The C compiler accepts C source code and produces assembly language source code. See the TMS320C6000 Optimizing C Compiler User’s Guide for details. ❏ The assembler translates assembly language source files into machine language object files. The machine language is based on common object file format (COFF). See the TMS320C6000 Assembly Language Tools User’s Guide for details.
Code Composer Studio Integrated Development Environment 1.3 Code Composer Studio Integrated Development Environment The Code Composer Studio Integrated Development Environment (IDE) is designed to allow you to edit, build, and debug DSP target programs. 1.3.1 Program Code Editing Features Code Composer Studio allows you to edit C and assembly source code. You can also view C source code with the corresponding assembly instructions shown after the C statements.
Code Composer Studio Integrated Development Environment 1.3.2 Application Building Features Within Code Composer Studio, you create an application by adding files to a project. The project file is used to build the application. Files in a project can include C source files, assembly source files, object files, libraries, linker command files, and include files. You can use a window to specify the options you want to use when compiling, assembling, and linking a project.
DSP/BIOS Plug-ins 1.4 DSP/BIOS Plug-ins During the analysis phase of the software development cycle, traditional debugging features are ineffective for diagnosing subtle problems that arise from time-dependent interactions. The Code Composer Studio plug-ins provided with DSP/BIOS support such real-time analysis. You can use them to visually probe, trace, and monitor a DSP application with minimal impact on real-time performance.
DSP/BIOS Plug-ins ❏ It serves as a visual editor for creating and setting properties for run-time objects that are used by the target application’s DSP/BIOS API calls. These objects include software interrupts, I/O pipes, and event logs. When you open a configuration file in Code Composer Studio, a window like the following one appears.
DSP/BIOS Plug-ins 1.4.2 DSP/BIOS API Modules Unlike traditional debugging, which is external to the executing program, the DSP/BIOS features require the target program to be linked with certain DSP/BIOS API modules. A program can use one or more DSP/BIOS modules by defining DSP/BIOS objects in a configuration file, declaring these objects as external, and calling DSP/BIOS API functions in the source code. Each module has a separate C header file or assembly macro file you can include in your program.
DSP/BIOS Plug-ins ❏ MEM. The memory module allows you to specify the memory segments required to locate the various code and data sections of a target program. ❏ PIP. The data pipe module manages data pipes, which are used to buffer streams of input and output data. These data pipes provide a consistent software data structure you can use to drive I/O between the DSP device and other real-time peripheral devices. ❏ PRD.
Hardware Emulation and Real-Time Data Exchange 1.5 Hardware Emulation and Real-Time Data Exchange TI DSPs provide on-chip emulation support that enables Code Composer Studio to control program execution and monitor real-time program activity. Communication with this on-chip emulation support occurs via an enhanced JTAG link. This link is a low-intrusion way of connecting into any DSP system. An emulator interface, like the TI XDS510, provides the host side of the JTAG connection.
Hardware Emulation and Real-Time Data Exchange RTDX consists of both target and host components. A small RTDX software library runs on the target DSP. The designer's DSP application makes function calls to this library’s API in order to pass data to or from it. This library uses the on-chip emulation hardware to move data to or from the host platform via an enhanced JTAG interface. Data transfer to the host occurs in real time while the DSP application is running.
Third-Party Plug-ins RTDX is well-suited for a variety of control, servo, and audio applications. For example, wireless telecommunications manufacturers can capture the outputs of their vocoder algorithms to check the implementations of speech applications. Embedded control systems also benefit.
Code Composer Studio Files and Variables 1.7 Code Composer Studio Files and Variables The following sections provide an overview of the folders that contain the Code Composer Studio files, the types of files you use, and the environment variables used by Code Composer Studio. 1.7.1 Installation Folders The installation process creates the subfolders shown here in the folder where you install Code Composer Studio (typically c:\ti).
Code Composer Studio Files and Variables 1.7.2 File Extensions While using Code Composer Studio, you work with files that have the following file-naming conventions: ❏ project.mak. Project file used by Code Composer Studio to define a project and build a program ❏ program.c. C program source file(s) ❏ program.asm. Assembly program source file(s) ❏ filename.h. Header files for C programs, including header files for DSP/BIOS API modules ❏ filename.lib. Library files ❏ project.cmd.
Code Composer Studio Files and Variables 1.7.3 Environment Variables The installation procedure defines the following variables in your autoexec.bat file (for Windows 95 and 98) or as environment variables (for Windows NT): Table 1–1 Environment Variables 1.7.4 Variable Description C6X_A_DIR A search list used by the assembler to find library and include files for DSP/BIOS, RTDX, and the code generation tools. See the TMS320C6000 Assembly Language Tools User’s Guide for details.
1-18
Chapter 2 Developing a Simple Program This chapter introduces Code Composer Studio and shows the basic process used to create, build, debug, and test programs. In this chapter, you create and test a simple program that displays a hello world message. This tutorial introduces you to some of the key features of Code Composer Studio. The intention is not to provide an exhaustive description of every feature. Instead, the objective is to prepare you to begin DSP software development with Code Composer Studio.
Creating a New Project 2.1 Creating a New Project In this chapter, you create a project with Code Composer Studio and add source code files and libraries to the project. Your project uses standard C library functions to display a hello world message. 1) If you installed Code Composer Studio in c:\ti, create a folder called hello1 in the c:\ti\myprojects folder. (If you installed elsewhere, create a folder within the myprojects folder in the location where you installed.
Adding Files to a Project 2.2 Adding Files to a Project 1) Choose Project→Add Files to Project. Select hello.c and click Open. 2) Choose Project→Add Files to Project. Select Asm Source Files (*.a*, *.s*) in the Files of type box. Select vectors.asm and click Open. This file contains assembly instructions needed to set the RESET interrupt service fetch packets (ISFPs) to branch to the program’s C entry point, c_int00. (For more complex programs, you can define additional interrupt vectors in vectors.
Reviewing the Code When building the program, Code Composer Studio finds files by searching for project files in the following path order: 2.3 ❏ The folder that contains the source file. ❏ The folders listed in the Include Search Path for the compiler or assembler options (from left to right). ❏ The folders listed in the definitions of the C6X_C_DIR (compiler) and C6X_A_DIR (assembler) environment variables (from left to right).
Building and Running the Program #ifdef FILEIO /* clear char arrays */ for (i = 0; i < BUFSIZE; i++) { scanStr[i] = 0 /* deliberate syntax error */ fileStr[i] = 0; } /* read a string from stdin */ scanf("%s", scanStr); /* open a file on the host and write char array */ fptr = fopen("file.txt", "w"); fprintf(fptr, "%s", scanStr); fclose(fptr); /* open a file on the host and read char array */ fptr = fopen("file.
Building and Running the Program To build and run the program, follow these steps: 1) Choose Project→Rebuild All or click the (Rebuild All) toolbar button. Code Composer Studio recompiles, reassembles, and relinks all the files in the project. Messages about this process are shown in a frame at the bottom of the window. 2) Choose File→Load Program. Select the program you just rebuilt, myhello.out, and click Open.
Changing Program Options and Fixing Syntax Errors 2.5 Changing Program Options and Fixing Syntax Errors In the previous section, the portion of the program enclosed by the preprocessor commands (#ifdef and #endif) did not run because FILEIO was undefined. In this section, you set a preprocessor option with Code Composer Studio. You also find and correct a syntax error. 1) Choose Project→Options. 2) In the Compiler tab of the Build Options window, select Preprocessor from the Category list.
Changing Program Options and Fixing Syntax Errors 3) If you are programming for the TMS320C6701 and your program uses floating point values, go to the Target Version field and select 67xx from the pull-down list. 4) Click OK to save your new option settings. (Rebuild All) toolbar button. 5) Choose Project→Rebuild All or click the You need to rebuild all the files whenever the project options change. 6) A message says the program contains compile errors. Click Cancel. Scroll up in the Build tab area.
Using Breakpoints and the Watch Window 2.6 Using Breakpoints and the Watch Window When you are developing and testing programs, you often need to check the value of a variable during program execution. In this section, you use breakpoints and the Watch Window to view such values. You also use the step commands after reaching the breakpoint. 1) Choose File→Reload Program. 2) Double-click on the hello.c file in the Project View.
Using Breakpoints and the Watch Window 10) At the prompt, type goodbye and click OK. Notice that the Stdout tab shows the input text in blue. Also notice that the Watch Window now shows the value of *scanStr. After you type an input string, the program runs and stops at the breakpoint. The next line to be executed is highlighted in yellow. 11) Click the to fprintf().
Using the Watch Window with Structures 2.7 Using the Watch Window with Structures In addition to watching the value of a simple variable, you can watch the values of the elements of a structure. 1) Right-click on the Watch Window area and choose Insert New Expression from the pop-up list. 2) Type str as the Expression and click OK. A line that says +str = {...} appears in the Watch Window. The + sign indicates that this is a structure. Recall from section 2.
Profiling Code Execution Time 2.8 Profiling Code Execution Time In this section, you use the profiling features of Code Composer Studio to gather statistics about the execution of the standard puts() function. In section 3.4, page 3-8, you compare these results to the results for using the DSP/BIOS API to display the hello world message. 1) Choose File→Reload Program. 2) Choose Profiler→Enable Clock. A check mark appears next to this item in the Profiler menu. This clock counts instruction cycles.
Profiling Code Execution Time Profile-points are handled before the profile-point line is executed. They report the number of instruction cycles since the previous profile-point or since the program started running. As a result, the statistics for the second profile-point report the number of cycles from when puts() started executing until it finished executing. 9) Choose Profiler→View Statistics. An area appears at the bottom of the window that displays statistics about the profile-points.
Things to Try 14) Before continuing to the next chapter (after completing section 2.9, page 2-14), perform the following steps to free the resources used in your profiling session: 2.9 ■ Go to the Profiler menu and uncheck Enable Clock. ■ Close the Profile Statistics window by right-clicking and choosing Hide from the pop-up menu. ■ Go to Profiler→Profile-points. Select Delete All and click OK. ■ Go to the View menu and uncheck Mixed Source/ASM.
Chapter 3 Developing a DSP/BIOS Program This chapter introduces DSP/BIOS and shows how to create, build, debug, and test programs that use DSP/BIOS. In this chapter, you optimize the hello world program you created in Chapter 2 by using DSP/BIOS. This chapter requires a physical board and cannot be carried out using a software simulator. Also, this chapter requires the DSP/BIOS components of Code Composer Studio. Topic Page 3.1 Creating a Configuration File . . . . . . . . . . . . . . . . . . . . . .
Creating a Configuration File 3.1 Creating a Configuration File Another way to implement the hello world program is to use the LOG module provided with the DSP/BIOS API. You can use the DSP/BIOS API to provide basic run-time services within your embedded programs. The API modules are optimized for use on real-time DSPs. Unlike C library calls such as puts(), DSP/BIOS enables real-time analysis without halting your target hardware.
Creating a Configuration File You see a window like the following. You can expand and contract the list by clicking the + and - symbols on the left. The right side of the window shows properties of the object you select in the left side of the window. 4) Right-click on the LOG - Event Log Manager and choose Insert LOG from the pop-up menu. This creates a LOG object called LOG0. 5) Right-click on the name of the LOG0 object and choose Rename from the pop-up menu. Change the object’s name to trace.
Adding DSP/BIOS Files to a Project Although these files have extensions of .s62 and .h62, they can also be used with the TMS320C6701. DSP/BIOS does not need to use the floating-point instructions supported by the TMS320C6701, therefore only one version of the software is required to support both DSPs. If you are using the TMS320C6701 with DSP/BIOS, open the Global Settings property page in the configuration and change the DSP Type property. This controls the libraries with which the program is linked. 3.
Adding DSP/BIOS Files to a Project 5) In the Project View area, right-click on the vectors.asm source file and choose Remove from project in the pop-up menu. The hardware interrupt vectors are automatically defined by the DSP/BIOS configuration file. 6) Right-click on the RTS6201.lib library file and remove it from the project. This library is automatically included by the myhellocfg.cmd file. 7) Double-click on the hello.c program to open it for editing.
Testing with Code Composer Studio interrupts and hardware interrupts to occur. Chapter 5 through Chapter 7 explain these types of events. 10) Choose File→Save or press Ctrl+S to save your changes to hello.c. 11) Choose Project→Options. Choose the Preprocessor category. Remove FILEIO from the Define Symbols box in the Compiler tab. Then click OK. 12) Choose Project→Rebuild All or click the 3.3 (Rebuild All) toolbar button. Testing with Code Composer Studio Now you can test the program.
Testing with Code Composer Studio 9) Choose Tools→RTDX to open the RTDX control window. Select RTDX Disable from the pull-down list, then right-click on the RTDX area and select Hide. Note: Profiling and RTDX Cannot Be Used Together on Some Targets The DSP/BIOS plug-ins use RTDX for host/target communication. On some DSP targets (for example, the TMS320C6201) you cannot use both profiling and RTDX at the same time.
Profiling DSP/BIOS Code Execution Time 3.4 Profiling DSP/BIOS Code Execution Time Earlier, you used the profiling features of Code Composer Studio to find the number of cycles required to call puts(). Now, you can do the same for the call to LOG_printf. 1) Choose File→Reload Program. 2) Choose Profiler→Enable Clock. Make sure you see a check mark next to this item in the Profiler menu. 3) Double-click on the hello.c file in the Project View. 4) Choose View→Mixed Source/ASM.
Profiling DSP/BIOS Code Execution Time Calls to LOG_printf are efficient because the string formatting is performed on the host PC rather than on the target DSP. LOG_printf takes about 36 instruction cycles compared to about 1700 for puts() measured at the end of Chapter 2. You can leave calls to LOG_printf in your code for system status monitoring with very little impact on code execution. 12) Click (Halt) or press Shift F5 to stop the program.
Things to Try 3.5 Things to Try To explore Code Composer Studio, try the following: ❏ Load myhello.out and put a breakpoint on the line that calls LOG_printf. Use Debug→Breakpoints to add a breakpoint at IDL_F_loop. (Type IDL_F_loop in the Location box and click Add.) Run the program. At the first breakpoint, use View→CPU Registers→CPU Register to see a list of register values. Notice that GIE is 0, indicating that interrupts are disabled while the main function is executing. Run to the next breakpoint.
Chapter 4 Testing Algorithms and Data from a File This chapter shows the process for creating and testing a simple algorithm and introduces additional Code Composer Studio features. In this chapter, you create a program that performs basic signal processing. You expand on this example in the following two chapters. You create and test a simple algorithm using data stored in a file on your PC. You also use Probe Points, graphs, animation, and GEL files with Code Composer Studio. Topic Page 4.
Opening and Examining the Project 4.1 Opening and Examining the Project You begin by opening a project with Code Composer Studio and examining the source code files and libraries used in that project. 1) If you installed Code Composer Studio in c:\ti, create a folder called volume1 in the c:\ti\myprojects folder. (If you installed elsewhere, create a folder within the myprojects folder in the location where you installed.) 2) Copy all files from the c:\ti\c6000\tutorial\volume1 folder to this new folder.
Opening and Examining the Project 6) Expand the Project View by clicking the + signs next to Project, VOLUME.MAK, Include, Libraries, and Source. The files used in this project are: ■ volume.c. This is the source code for the main program. You examine the source code in the next section. ■ volume.h. This is a header file included by volume.c to define various constants and structures. ■ load.asm.
Reviewing the Source Code 4.2 Reviewing the Source Code Double-click on the volume.c file in the Project View to see the source code in the right half of the Code Composer Studio window. Notice the following parts of this example: ❏ After the main function prints a message, it enters an infinite loop. Within this loop, it calls the dataIO and processing functions. ❏ The processing function multiplies each value in the input buffer by the gain and puts the resulting values into the output buffer.
Reviewing the Source Code /* loop forever */ while(TRUE) { /* Read using a Probe Point connected to a host file. */ dataIO(); /* apply gain */ processing(input, output); } } /* ======== processing ======== * * FUNCTION: apply signal processing transform to input signal. * PARAMETERS: address of input and output buffers. * RETURN VALUE: TRUE.
Adding a Probe Point for File I/O 4.3 Adding a Probe Point for File I/O In this section, you add a Probe Point, which reads data from a file on your PC. Probe Points are a useful tool for algorithm development.
Adding a Probe Point for File I/O 6) Choose File→File I/O. The File I/O dialog appears so that you can select input and output files. 7) In the File Input tab, click Add File. 8) Choose the sine.dat file. Notice that you can select the format of the data in the Files of Type box. The sine.dat file contains hex values for a sine waveform. 9) Click Open to add this file to the list in the File I/O dialog. A control window for the sine.dat file appears. (It may be covered by the Code Composer Studio window.
Adding a Probe Point for File I/O ■ The Length field specifies how many samples from the data file are read each time the Probe Point is reached. You use 100 because that is the value set for the BUFSIZE constant in volume.h (0x64). ■ The Wrap Around option causes Code Composer Studio to start reading from the beginning of the file when it reaches the end of the file.
Displaying Graphs 4.4 Displaying Graphs If you ran the program now, you would not see much information about what the program was doing. You could set watch variables on addresses within the inp_buffer and out_buffer arrays, but you would need to watch a lot of variables and the display would be numeric rather than visual. Code Composer Studio provides a variety of ways to graph data processed by your program. In this example, you view a signal plotted against time.
Animating the Program and Graphs 4.5 Animating the Program and Graphs So far, you have placed a Probe Point, which temporarily halts the target, transfers data from the host PC to the target, and resumes execution of the target application. However, the Probe Point does not cause the graphs to be updated. In this section, you create a breakpoint that causes the graphs to be updated and use the Animate command to resume execution automatically after the breakpoint is reached. 1) In the Volume.
Animating the Program and Graphs buffer contains the values just read from sine.dat, while the output buffer contains the last set of values processed by the processing function. Note: Target Halts at Probe Points Code Composer Studio briefly halts the target whenever it reaches a Probe Point. Therefore, the target application may not meet real-time deadlines if you are using Probe Points. At this stage of development, you are testing the algorithm.
Adjusting the Gain 4.6 Adjusting the Gain Recall from section 4.2, page 4-4 that the processing function multiplies each value in the input buffer by the gain and puts the resulting values into the output buffer. It does this by performing the following statement within a while loop: *output++ = *input++ * gain; This statement multiplies a value in inp_buffer by the gain and places it in the corresponding location in the out_buffer. The gain is initially set to MINGAIN, which is defined as 1 in volume.h.
Viewing Out-of-Scope Variables 4.7 Viewing Out-of-Scope Variables You have used the Watch Window to view and change the values of variables. Sometimes you want to examine variables when they are not currently in scope at the current breakpoint. You can do this by using the call stack. 1) Click (Halt) or press Shift F5 to stop the program. 2) Review the volume.c program within Code Composer Studio (or by looking at section 4.2, page 4-4).
Viewing Out-of-Scope Variables 10) Notice that the Watch window area says this variable is an unknown identifier. This shows that *input is not defined within the scope of the dataIO function. 11) Choose View→Call Stack. You see the call stack area next to the Watch window area. 12) Click on main() in the call stack area to see the value of *input within the scope of the main function. (The value should be 0, but may differ if you have modified the sine.dat file.
Using a GEL File 4.8 Using a GEL File Code Composer Studio provides another way of modifying a variable. This method uses GEL, an extension language, to create small windows that allow you to modify variables. 1) Choose File→Load GEL. In the Load GEL File dialog box, select the volume.gel file and click Open. 2) Choose GEL→Application Control→Gain. This item was added to your menus when you loaded the GEL file. 3) If you have halted the program, click the (Animate) toolbar button.
Adjusting and Profiling the Processing Load 4.9 Adjusting and Profiling the Processing Load In Chapter 2, you used profile-points to measure the number of cycles required to call puts(). Now, you use profile-points to see the effect of changing the processingLoad variable, which is passed to the assembly load routine. The processingLoad is initially set to BASELOAD, which is defined as 1 in volume.h. 1) Choose Profiler→Enable Clock. Make sure you see a check mark next to this item in the Profiler menu.
Adjusting and Profiling the Processing Load 12) Type 2 as the new load and click Execute. The maximum number of cycles for the second profile-point changes to 2018. The number of cycles increases by about 1000 when you increment the processingLoad by 1. These instruction cycles are performed within the load function, which is stored in load.asm. 13) Right-click on the Profile Statistics area and choose Clear All from the pop-up menu. This resets the statistics to 0.
Things to Try 4.10 Things to Try To explore using Code Composer Studio, try the following: ❏ Add processingLoad to the Watch window. When you use the Load GEL control, the processingLoad value is updated in the Watch window. ❏ Right-click on the Watch window and choose Insert New Expression. Click the Help button and read about the display formats you can use. Experiment with various display formats. For example, you can type *input,x as the expression to view the sine input in hexadecimal format.
Chapter 5 Debugging Program Behavior This chapter introduces techniques for debugging a program and several DSP/BIOS plug-ins and modules. In this chapter, you modify the example from Chapter 4 to create a program that schedules its functions and allows for multi-threading. You view performance information for debugging purposes.
Opening and Examining the Project 5.1 Opening and Examining the Project You begin by opening a project with Code Composer Studio and examining the source code files and libraries used in that project. 1) If you installed Code Composer Studio in c:\ti, create a folder called volume2 in the c:\ti\myprojects folder. (If you installed elsewhere, create a folder within the myprojects folder in the location where you installed.) 2) Copy all files from the c:\ti\c6000\tutorial\volume2 folder to this new folder.
Reviewing the Source Code 5.2 Reviewing the Source Code This example modifies the example from Chapter 4 to introduce real-time behavior. Rather than having the main function loop forever, the data I/O in the real application is likely to happen as a result of a periodic external interrupt. A simple way to simulate a periodic external interrupt in the example is to use the timer interrupt from the on-chip timer. 1) Double-click on the volume.
Reviewing the Source Code ■ The dataIO function calls SWI_dec, which decrements a counter associated with a software interrupt object. When the counter reaches 0, the software interrupt schedules its function for execution and resets the counter. The dataIO function simulates hardware-based data I/O. A typical program accumulates data in a buffer until it has enough data to process. In this example, the dataIO function is performed 10 times for each time the processing function is performed.
Reviewing the Source Code /* ======== processing ======== * * FUNCTION: Called from processing_SWI to apply signal * processing transform to input signal. * PARAMETERS: Address of input and output buffers. * RETURN VALUE: TRUE.
Modifying the Configuration File 5.3 Modifying the Configuration File A DSP/BIOS configuration file has already been created for this example. In this section, you examine the objects that have been added to the default configuration. 1) In the Project View, double-click on the volume.cdb file (in the DSP/BIOS Config folder) to open it. 2) Click the + signs next to the CLK, LOG, and SWI managers.
Modifying the Configuration File 4) Right-click on the LOG object called LOG_system. From the pop-up menu, select Properties. You see the properties dialog for this object. At run time, this log stores events traced by the system for various DSP/BIOS modules. 5) Change the buflen property to 512 words and click OK. 6) Highlight the CLK object called dataIO_CLK. Notice that the function called when this CLK object is activated is _dataIO. This is the dataIO function in volume.c.
Modifying the Configuration File 7) Since the dataIO function is no longer run within main, what causes this CLK object to run its function? To find out, right-click on the CLK - Clock Manager object. From the pop-up menu, select Properties. You see the Clock Manager Properties dialog. Notice that the CPU Interrupt for the Clock Manager is HWI_INT14. This property is gray because it is actually set by the HWI_INT14 object.
Modifying the Configuration File 10) Right-click on the processing_SWI software interrupt object. From the pop-up menu, select Properties. ■ function. When this software interrupt is activated, the processing function runs. This function is shown in section 5.2, page 5–5. ■ mailbox. The mailbox value can control when a software interrupt runs. Several API calls affect the value of the mailbox and can post the software interrupt depending on the resulting value.
Viewing Thread Execution with the Execution Graph 5.4 Viewing Thread Execution with the Execution Graph While you could test the program by putting a Probe Point within the processing function and view graphs of input and output data (as you did in the previous chapter), you have already tested the signal processing algorithm. At this stage of development, your focus is on making sure the threads can meet their real-time deadlines. 1) Choose File→Load Program. Select the program you just built, volume.
Viewing Thread Execution with the Execution Graph 9) Choose Debug→Run or click the Graph should look similar to this: (Run) toolbar button. The Execution 10) The marks in the Time row show each time the Clock Manager ran the CLK functions. Count the marks between times the processing_SWI object was running. There should be 10 marks. This indicates that the processing_SWI object ran its function every tenth time the dataIO_CLK object ran its function.
Changing and Viewing the Load 5.5 Changing and Viewing the Load Using the Execution Graph, you saw that the program meets its real-time deadlines. However, the signal processing functions in a typical program must perform more complex and cycle consuming work than multiplying a value and copying it to another buffer. You can simulate such complex threads by increasing the cycles consumed by the load function. 1) Choose Tools→DSP/BIOS→CPU Load Graph. A blank CPU Load Graph appears.
Changing and Viewing the Load 7) Right-click on the Execution Graph and choose Clear from the pop-up menu. Notice that the program still meets its real-time deadline. There are 10 time marks between each execution of the processing_SWI function. 8) Using the GEL control, change the load to 200 and click Execute. 9) Right-click on the Execution Graph and choose Clear from the pop-up menu. One or two of the time marks occur while the processing_SWI function is executing.
Changing and Viewing the Load 12) Using the GEL control, change the load to 1500 and click Execute. The CPU Load Graph and the Execution Graph stop updating. This is because Execution Graph data is sent to the host within an idle thread, which has the lowest execution priority within the program. Because the higher-priority threads are using all the processing time, there is not enough time for the host control updates to be performed. The program is now missing its real-time deadline.
Analyzing Thread Statistics 5.6 Analyzing Thread Statistics You can use other DSP/BIOS controls to examine the load on the DSP and the processing statistics for the processing_SWI object. 1) Choose Tools→DSP/BIOS→Statistics View. A Statistics View area that says Load DSP/BIOS program and/or set property to use control appears. It says this because you need to select the statistics you want to view. 2) Right-click on the Statistics View area and choose Property Page from the pop-up menu.
Analyzing Thread Statistics 5) If you have halted the program, click the (Run) toolbar button. 6) Notice the Max value in the Statistics View. SWI statistics are measured in instruction cycles. 7) Using the GEL control, increase the load and click Execute. Notice the change in the Max value for the number of instructions performed from the beginning to the end of processing_SWI increases. 8) Experiment with different load values.
Adding Explicit STS Instrumentation 5.7 Adding Explicit STS Instrumentation In the previous section, you used the Statistics View to see the number of instructions performed during a software interrupt’s execution. If you use a configuration file, DSP/BIOS supports such statistics automatically. This is called implicit instrumentation. You can also use API calls to gather other statistics. This is called explicit instrumentation. 1) In the Project View, double-click on the volume.
Viewing Explicit Instrumentation 5.8 Viewing Explicit Instrumentation To view information provided by the explicit instrumentation calls you added, you use the Statistics View and the RTA Control Panel. 1) Choose File→Load Program. Select the program you just rebuilt, volume.out, and click Open. 2) Choose Tools→DSP/BIOS→RTA Control Panel. 3) Right-click on the RTA Control Panel area and deselect Allow Docking to display the RTA Control Panel in a separate window.
Viewing Explicit Instrumentation 9) Multiply the Max value for processingLoad_STS by 4. Because you used the CLK_gethtime function to benchmark the processing load, the statistics for processingLoad_STS are measured in on-chip timer counter increments. SWI statistics are measured in instruction cycles. On TMS320C6000 DSPs, the high-resolution time is incremented every 4 instruction cycles. Therefore, to convert the processingLoad_STS units to instruction cycles, you multiply by 4.
Things to Try 15) Remove the check mark from the enable USER0 trace box in the RTA Control Panel. 16) Right-click on the Statistics View and choose Clear from the pop-up menu. 17) Notice that no values are updated for processingLoad_STS. This is because disabling the USER0 trace causes the following statement in the program to be false: if (TRC_query(TRC_USER0) == 0) As a result, the calls to STS_set and STS_delta are not performed. 18) Before continuing to the next chapter (after completing section 5.
Chapter 6 Analyzing Real-Time Behavior This chapter introduces techniques for analyzing and correcting real-time program behavior. In this chapter, you analyze real-time behavior and correct scheduling problems using the example from Chapter 5. You use RTDX (Real-Time Data Exchange) to make real-time changes to the target, use DSP/BIOS periodic functions, and set software interrupt priorities. This chapter requires a physical board and cannot be carried out using a software simulator.
Opening and Examining the Project 6.1 Opening and Examining the Project In this chapter, you modify the example you worked on in the previous chapter. Note: Copy Example Files if Previous Chapter Not Completed If you did not complete the previous chapter, you can copy example files from the volume3 folder that reflect the state of the example at the end of the previous chapter.
Modifying the Configuration File 6.2 Modifying the Configuration File For this example, you need to add one new object to the configuration file. (The volume.cdb file in the c:\ti\c6000\tutorial\volume4\ folder already contains this object.) 1) In the Project View, double-click on the volume.cdb file to open it. 2) Select LOG_system, change the buflen property to 512 words, and click OK (as you did in section 5.3, page 5–7). 3) Right-click on the PRD manager and choose Insert PRD from the pop-up menu.
Modifying the Configuration File 7) Click the + sign next to the SWI manager. A SWI object called PRD_swi was added automatically. This software interrupt executes periodic functions at run time. Therefore, all PRD functions are called within the context of a software interrupt and can yield to hardware interrupts. In contrast, CLK functions run in the context of a hardware interrupt. (The KNL_swi object runs a function that runs the TSK manager.
Reviewing the Source Code Changes 6.3 Reviewing the Source Code Changes Double-click on the volume.c file in the Project View to see the source code in the right half of the Code Composer Studio window. Since you copied the volume.c file from the c:\ti\c6000\tutorial\volume4\ folder to your working folder, the source code now contains the following differences from the source code used in the previous chapter: ❏ Added the following to the list of included header files: #include
Reviewing the Source Code Changes This function uses RTDX API functions to change the load of the processing signal in real time. Notice the following aspects of these changes: 6-6 ❏ The call to RTDX_enableInput enables the input channel called control_channel so that data can flow on it from the host to the target. At run time, a Visual Basic host client writes a load control value on that channel, thereby sending it to the target application.
Using the RTDX Control to Change the Load at Run Time 6.4 Using the RTDX Control to Change the Load at Run Time While you could test the program by putting a Probe Point within the processing function and view graphs of input and output data (as you did in section 4.3, page 4-6), you have already tested the signal processing algorithm. At this stage of development, your focus is on making sure the threads you have added can still meet their real-time deadlines.
Using the RTDX Control to Change the Load at Run Time 7) Right-click on the Statistics View area and choose Property Page from the pop-up menu. Highlight the items shown here. 8) Click OK. 9) Resize the Statistics area to see the fields for the statistics you selected. 10) Right-click on the RTA Control Panel and choose Property Page from the pop-up menu. 11) Set the Refresh Rate for Message Log/Execution Graph to 1 second and the Refresh Rate for Statistics View/CPU Load Graph to 0.5 seconds.
Using the RTDX Control to Change the Load at Run Time 14) Using the Windows Explorer, run loadctrl.exe, which is located in your working folder. The Load Control window appears. Each mark on the slider changes the load value by 50, or about 50,000 instructions. This simple Windows application was written using Visual Basic and RTDX. If you have Visual Basic, you can examine the source files for the loadctrl.exe application stored in the c:\ti\c6000\tutorial\volume4\ folder.
Using the RTDX Control to Change the Load at Run Time PRD statistics are measured in PRD ticks. SWI statistics are measured in instruction cycles. The Max and Average fields for loadchange_PRD show that there is less than a full PRD tick between the time this function needs to start running and its completion. (The actual numbers shown may vary.) 16) Use the Load Control window to gradually increase the processing load.
Modifying Software Interrupt Priorities 6.5 Modifying Software Interrupt Priorities To understand why the program is not meeting its real-time deadline, you need to examine the priorities of the software interrupt threads. 1) Select Debug→Halt to halt the target. 2) In the Project View, double-click on the volume.cdb file to open it. 3) Highlight the SWI manager. Notice the SWI object priorities shown in the right half of the window. (The KNL_swi object runs a function that runs the TSK manager.
Things to Try 9) Select Debug→Run to run the example again. Use the RTDX-enabled Windows application loadctrl.exe to change the load at run time (as in section 6.4, page 6-7). 10) Notice that you can now increase the load without causing PRD_swi to miss its real-time deadline. Note: Starving Idle Loop It is still possible to starve the idle loop by increasing the processing load to maximum. 11) Before continuing to the next chapter (after completing section 6.
Learning More the CPU load? Now, add calls to STS_set and STS_delta in the dataIO function. How does this change affect the CPU load? Why? Consider the frequency at which each function is executed. Even small increases to the processing requirements for functions that run frequently can have dramatic effects on CPU load. 6.
6-14
Chapter 7 Connecting to I/O Devices This chapter introduces RTDX and DSP/BIOS techniques for implementing I/O. In this chapter, you connect a program to an I/O device using RTDX and DSP/BIOS. You also use the HST, PIP, and SWI modules of the DSP/BIOS API. This chapter requires a physical board and cannot be carried out using a software simulator. Also, this chapter requires the DSP/BIOS and RTDX components of Code Composer Studio. Topic Page 7.1 Opening and Examining the Project . . . . . . . . . . . .
Opening and Examining the Project 7.1 Opening and Examining the Project You begin by opening a project with Code Composer Studio and examining the source code files and libraries used in that project. 1) If you installed Code Composer Studio in c:\ti, create a folder called hostio in the c:\ti\myprojects folder. (If you installed elsewhere, create a folder within the myprojects folder in the location where you installed.) 2) Copy all files from the c:\ti\c6000\tutorial\hostio1 folder to this new folder.
Reviewing the C Source Code 7.2 Reviewing the C Source Code The example in this chapter simulates a DSP application that digitizes an audio signal, adjusts its volume, and produces an analog output at the adjusted volume. For simplicity, no actual device is used to send and receive analog data in this example. Instead, the example tests the algorithm using host-generated digital data. Input and output data and volume control are transferred between the host and the target using RTDX.
Reviewing the C Source Code ■ While control_channel is enabled by the target via a call to RTDX_enableInput, the other RTDX channels are not enabled from this program. Instead, a host program described in the next section enables these channels. This is because the slider control, which uses the control_channel, is viewed as an integral part of the application. By enabling this channel in the target program, you know the channel is enabled while the application is running.
Reviewing the C Source Code while (TRUE) { /* Read a new volume when the hosts send it */ if (!RTDX_channelBusy(&control_channel)){ RTDX_readNB(&control_channel, &volume, sizeof(volume)); } while (!RTDX_isInputEnabled(&A2D_channel)){ RTDX_Poll(); /* poll comm channel for input */ } /* * A2D: get digitized input (get signal from the host through * RTDX). If A2D_channel is enabled, read data from the host.
Reviewing the Signalprog Application 7.3 Reviewing the Signalprog Application The source code for the Visual Basic signalprog.exe application is available in the signalfrm.frm file. Details about this application are provided in the signalprog.pdf Adobe Acrobat file. In this section, you examine a few of the routines and functions that are important for this example. ❏ Test_ON. This routine runs when you click the Test_ON button.
Running the Application 7.4 Running the Application 1) Choose Project→Build or click the (Incremental Build) toolbar button. 2) Choose File→Load Program. Select hostio.out and click Open. 3) Choose Tools→RTDX. 4) Click Configure in the RTDX area of the window. In the General Settings tab of the RTDX Properties dialog, select Continuous RTDX mode. Then, click OK. 5) Change RTDX Disable to RTDX Enable in the RTDX area. This changes the Configure button to Diagnostics. 6) Choose Tools→DSP/BIOS→Message Log.
Running the Application The signalprog.exe program can be started at any point. It does not use RTDX until you click the Test On button. 9) Resize the signalprog window so that it is taller. This allows you to see the axis labels. 10) Click Test On in the signalprog window. This starts the input and output channels.
Running the Application 11) Slide the control in the Volume Slider window. This changes the volume of the output signal. Watch the amplitude of the Received Signal graph change. (Only the scale values to the left and right of the graph change. The graph changes scale automatically to accommodate the size of the sine wave and the size of the window.) Note: Initial Setting of Volume Slider The initial setting of the Volume Slider bar is not synchronized with the application.
Modifying the Source Code to Use Host Channels and Pipes 7.5 Modifying the Source Code to Use Host Channels and Pipes Now you modify the example to use the host channels and pipes provided with DSP/BIOS. The modified example still tests your DSP algorithm in real time. Rather than generating a sine wave on the host, this time the data comes from a host file. The HST module provides a more direct path toward implementing I/O with peripheral devices. The HST module uses the PIP module for host I/O.
Modifying the Source Code to Use Host Channels and Pipes Void A2DscaleD2A(HST_Obj *inpChannel, HST_Obj *outChannel) { PIP_Obj *inp_PIP; PIP_Obj *out_PIP; sample *input; sample *output; Uns size; inp_PIP = HST_getpipe(inpChannel); out_PIP = HST_getpipe(outChannel); if ((PIP_getReaderNumFrames(inp_PIP) <= 0) || (PIP_getWriterNumFrames(out_PIP) <= 0)) { /* Software interrupt should not have been triggered! */ error(); } /* Read a new volume when the hosts send it */ if (!RTDX_channelBusy(&control_channel)) RTD
More about Host Channels and Pipes Calls to PIP_getReaderNumFrames and PIP_getWriterNumFrames then determine whether there is at least one frame in the input pipe that is ready to be read and one frame in the output pipe that can be written to. Using the same RTDX calls used in section 7.2, page 7-3, the function gets the volume setting from the RTDX control channel. The call to PIP_get gets a full frame from the input pipe.
Adding Channels and an SWI to the Configuration File 7.7 Adding Channels and an SWI to the Configuration File The A2DscaleD2A function is called by an SWI object and uses two HST objects. You create these objects in this section. (The hostio.cdb file in the c:\ti\c6000\tutorial\hostio2\ folder already contains these objects.) The A2DscaleD2A function also references two PIP objects, but these objects are created internally when you create the HST objects.
Adding Channels and an SWI to the Configuration File ■ mode. This property determines which end of the pipe the target program manages, and which end the Host Channel Control plug-in manages. An input channel sends data from the host to the target. An output channel sends data from the target to the host. ■ framesize. This property sets the size of each frame in the channel. Use 64 words—the same value as the BUFSIZE defined in section 7.2, page 7-3. ■ notify, arg0, arg1.
Adding Channels and an SWI to the Configuration File 5) Insert another HST object and rename it output_HST. 6) Set the following properties for the output_HST object and click OK. When this output channel contains an empty frame (because the target read and released a frame), it uses SWI_andn to clear the second bit of the mailbox.
Adding Channels and an SWI to the Configuration File 7) Right-click on the SWI manager and choose Insert SWI. 8) Rename the new SWI0 object to A2DscaleD2A_SWI. 9) Set the following properties for A2DscaleD2A_SWI and click OK. ■ function. This property causes the object to call the A2DscaleD2A function when this software interrupt is posted and runs. ■ mailbox. This is the initial value of the mailbox for this object.
Running the Modified Program 7.8 Running the Modified Program 1) Choose Project→Rebuild All or click the (Rebuild All) toolbar button. 2) Choose File→Load Program. Select the program you just rebuilt, hostio.out, and click Open. 3) Choose Tools→DSP/BIOS→Host Channel Control. The Host Channel Control lists the HST objects and allows you to bind them to files on the host PC and to start and stop the channels. 4) Choose Debug→Run or click the (Run) toolbar button.
7-18
This is a draft version printed from file: tutorialix.fm on 2/26/0 Index A animating program 4-10 archiver 1-5 .asm file 1-16 assembler 1-5 assembly optimizer 1-5 assembly vs. C 5-7 assembly, viewing with C source assertions 6-10 ATM module 1-10 2-12 B bin folder 1-15 bios folder 1-15 breakpoint creating 2-9 deleting 2-11 stepping from 2-10 building application 2-6 C C compiler 1-5 .c file 1-16 C vs. assembly 5-7 C62 module 1-10 c6201 vs.
Index environment variables C6X_A_DIR 1-17 C6X_C_DIR 1-17 PATH 1-17 EPROM programmer 1-5 examples folder 1-15 Execution Graph 5-10 explicit instrumentation 5-17 F file I/O 4-7 file streaming 1-8 floating-point support folders 1-15 search path 2-4 font, setting 2-4 function names 5-7 I IDL module 1-10, 3-10 idle loop 3-5, 5-3 ifdef symbols 2-7 implicit instrumentation 5-15 include files 3-5 inserting an object 3-3 instruction cycles 2-12 profiling 2-13 integrated development environment interrupts disabled
Index N naming conventions new project 2-2 5-7 O .obj file 1-16 object editing properties 5-7 inserting 3-3 renaming 3-3 options color 2-9, 4-13 font 2-4 options for project 2-7 .
Index sectti utility 3-10 SEM module 1-11 signalprog.exe 7-6 simulator iii, 1-2 SIO module 1-11 slider.
