April 4, 2001: Debugging Your C24x DSP Design Using Code Composer Studio Real-Time Monitor

1 This presentation was part of TI s Monthly TMS320 DSP Technology Webcast Series April 4, 2001: Debugging Your C24x DSP Design Using Code Composer Studio Real-Time Monitor To view this 1-hour 1 webcast presentation and Q&A session: http://www. www.ti.com/sc/.com/sc/webcasts-kbase-apr01apr01 For Related Technical References: http://www. www.ti.com/sc/.com/sc/webcasts-kbase-apr01relapr01rel For more information on TI Webcasts: http://www. www.ti.com/sc/.com/sc/webcasts-kbase-home

2 Debugging Your C24x DSP Design Using Code Composer Studio Real-Time Monitor Code Composer Studio, C24x, C2000, C5000, TMS320, and F24x are trademarks of Texas Instruments Incorporated 1 Copyright 2001 Texas Instruments. All rights reserved.

3 Host: Dave Pahl Worldwide C5000 TM Catalog DSP Product Manager 2

4 Presenter: Jeff Stafford Technical Staff Digital Control Systems 3

Objectives Learn the fundamentals of the Real-Time Monitor (RT-MON) architecture Understand how to instrument a target application with RT-MON to enable data transfer Learn how to use Code Composer Studio IDE to display your data when running from RAM or Flash 4 5

What is RT-MON? Real-Time MONitor Enables data to be continuously exchanged between an embedded application and Code Composer Studio IDE without stopping the processor Available on all TMS320C/F24x DSPs 5 RT-MON is a monitor program that runs on the TMS320C24x DSPs. RT-MON enables data to be continuously exchanged between an embedded application and Code Composer Studio IDE without stopping the processor. This is different from traditional stop-mode debug where users set breakpoints in order to take a data snapshot of the target. The breakpoints stop the processor which interferes with the dynamics of your system and can actually damage the hardware. RT-MON is available on all C24x DSPs and is part of your Code Composer Studio (CCS) Integrated Development Environment (IDE) installation. 6

Code Composer Studio with RT-MON Running 6 Here we see Code Composer Studio IDE running with the Real-Time Monitor installed. On a live PC we would see the Graph, Watch, Memory, and Register Windows updating continuously. RT-MON allows ISR code to continuously run while the developer observes the target performance via a graph. The user can change target variables from a Memory or Watch Window, and the target will use these new value. RT-MON extends the Code Composer Studio IDE to be interactive on a continuously running application. 7

RT-MON Architecture Real-Time Mode Host (PC) Code Composer Studio IDE Emulator JTAG Emulation Logic Message Passing Target (DSP) C24x CPU Memory Interface H/W INT 7 S/W User Code 7 The RT-MON architecture consists of a combination of hardware and software components. In this diagram: - The target DSP is shown on the right and the host PC on the left. - The emulation hardware is shown in light green. This consists of the emulation logic on the target, the emulator board connected to the host (typically a parallel port connection with a 510PP from Spectrum Digital), the JTAG interface that connects them, and the message passing logic. This emulation capability provides the hardware basis for the RT-MON data transfer. - The RT-MON software and user s application code are is shown in blue. - The C24x DSP CPU Memory Interface is shown in gold. - Code Composer Studio IDE is shown in gray. Using RT-MON affects how Code Composer Studio IDE communicates with the C24x DSP. Communication is either directly to the CPU (stop mode) or through an interrupt service routine (real-time mode). The interrupt service routine is known as the real-time monitor (INT7). (Continued) 8

RT-MON Architecture Real-Time Mode Host (PC) Code Composer Studio IDE Emulator JTAG Emulation Logic Message Passing Target (DSP) C24x CPU Memory Interface H/W INT 7 S/W User Code 7 RT-MON Architecture Real-Time Mode Continued In real time, Code Composer Studio IDE obtains memory and register content information by requesting this information through the RT-MON interrupt (INT7). Code Composer Studio IDE communicates to the RT-MON interrupt through the messaging unit, and accesses to this messaging unit through the standard JTAG interface pins. It is clear that the CPU can not be halted by the emulation logic. When in Real- Time Mode, the only access that the emulation logic has to the CPU and Memory is through INT7. 9

RT-MON Architecture Stop Mode Host (PC) Code Composer Studio IDE Emulator JTAG Emulation Logic Message Passing Target (DSP) C24x CPU Memory Interface H/W S/W User Code 8 At power-up, the DSP is in Stop Mode. Note that the only interface to memory from Code Composer Studio IDE and the emulation logic is through the CPU. In stop mode, Code Composer Studio IDE obtains memory and register content information by accessing the CPU scan path through the standard JTAG interface pins. Code Composer Studio IDE sends commands to the C24x DSP memory (on-chip or off-chip) and receives the results of the commands by using the scan path. While Code Composer Studio IDE is obtaining this information in stop mode, none of your code executes. The C24x DSP cannot respond to interrupts or execute non-isr code. 10

RT-MON Modes of Operation Run (F5) Stop Mode (Running) 9 Stop Mode (Halted)!REALTIME Halt or breakpoint Stop Mode is state at power-up go MON_GO REALTIME Real-Time Mode (Halted) Run (F5) Halt or breakpoint (non-isr code) Real-Time Mode (Run) There are four modes of Debug operation: Stop mode or Real-time mode, with the DSP either halted or running. Code Composer Studio (CCS) IDE starts in stop mode, with the DSP halted, at power-up. Normal debug would occur by running the DSP in stop mode and using breakpoints or user halts to update CCS IDE s Windows. This is defined as breakpoint level debug and is very useful for initial development of your code. Once the basic functionality of your code is confirmed, you can then add the RT-MON software and move from stop mode to real-time mode (shown in green). After power-up, you can move from stop mode to real-time mode (halted) by running to the label MON_GO and then selecting real-time from one of CCS IDE s pull-down menus. Executing code up to the label MON_GO allows the RT-MON software to setup its configuration and prepare for realtime communication. Once the code reaches this label, CCS IDE and the target DSP can safely go into real-time mode (halted). You can now run the DSP to execute both ISR and non-isr code. If a breakpoint, in non-isr code, is hit, then the DSP will be halted in real-time mode. You can exit real-time mode by de-selecting the real-time option from CCS IDE s debug pull-down menu, if the DSP is halted. 11

Entering Real-Time Mode MON_GO Open Command window from menu Tools\Command window Type go MON_GO Then Execute Dis-assembly window displays program counter at MON_GO (yellow bar) 10 Now that we understand the different RT-MON operating modes, let s look at the exact steps to follow from within CCS IDE to move from stop mode at power-up to running in real-time mode. First, make sure you have built and loaded your code, and reset the DSP. Then open the Command Window, this is available from CCS IDE s Tools menu. The Command Window accepts many commands, and we are going to use the go command to run the DSP to the label MON_GO. Note that labels in ASM, as in C, are case sensitive. Enter the command go MON_GO and select the Execute button. Note the Dis-Assembly window showing the code execution stopping at the label MON_GO. The yellow bar is the current position of the Program Counter. 12

Entering Real-Time Mode Enter Real-Time (halted) Mode after reaching MON_GO Enter Real-Time (running) Mode with F5 to RUN DSP 11 There are several ways to enter real-time mode, now that we have executed code up to the label MON_GO. You can either select the Real-time option from CCS IDE s Debug pull-down menu or execute the command real-time in the Command Window. This slide shows the selection of real-time from the debug pull-down menu. Note that two things happen after you enter real-time mode, the pull-down option has a check-mark next to it and in the lower left-hand corner of CCS IDE now lists REALTIME. Also note that DSP HALTED is listed showing that we are halted in real-time mode. We are now ready to run in real-time. Simply press F5 or select Run from the debug pull-down menu. The lower left-hand corner of CCS IDE now shows DSP RUNNING and REAL TIME indicating we are now running real-time mode. Both ISR and non-isr code are executing. 13

Update Windows in Real-Time Mode Right-mouse in window for menu Select Continuous Refresh 12 Plots, watch variables and registers continuously update Even though we are running in real time, you may notice that none of your CCS IDE windows are updating. We still need to enable the Continuous Refresh option for each window we want to update. You may have already noticed that each CCS IDE window has a menu associated with it and you can access it by clicking the right mouse key over the window. Within each window s menu is an option to select Continuous Refresh. Once you select this option, the window will start updating. Once this option is set, CCS IDE starts sending emulation commands through the JTAG interface. It is then interpreted by the emulation logic on the DSP, and passed by the message handling logic to the RT-MON interrupt (INT7). The RT-MON ISR then accesses memory though the CPU, but only after the CPU becomes available. This communication path allows CCS IDE to continuously update its windows and modification of target memory, with the application ISRs continuously running. 14

Set Window Refresh Rate Select Realtime Refresh Options Refresh Rate = 100 ms (shortest interval) Avoid Global Continuous Refresh Option 13 The rate which CCS IDE updates each selected window can be set from CCS IDE s View pull-down menu. The shortest interval for the refresh rate is 100 ms. Note that this refresh rate is intended as an interface to you, the user. It is not intended for trace or data logging. So 100 ms is more than fast enough for that purpose. To display real-time data, with real-time defined by the application, you would save data on the target within a RAM buffer. For example, say you have a timer interrupt that runs every 100 µs. Within this interrupt you calculate the actual speed of the motor you are controlling. Then you save this data to a circular buffer. Therefore, you are saving data points in this buffer every 100 µs. Even though CCS IDE will display the data at a 100 ms rate, it will be displaying data that has been stored on the target at a realtime rate of 100 µs. Avoid the option to select Global Continuous Refresh since this will update every CCS window and can greatly increase the data required to be transmitted by the RT-MON ISR. 15

Single-Step Step Through Non-Interrupt Code Single-step non-isr code (halted in real-time mode) ISRs continue to run! 14 If you want to single-step through non-isr code, maybe to debug your taskoriented state logic, you can do this by moving from Running in real-time mode to Halted in real-time mode. Just select Halt from CCS IDE s Debug pull-down menu or place a breakpoint in your non-isr code. This is especially useful if you have conditional non-isr code that has its dependencies within the ISR code. By single-stepping through the non-isr code, you can debug the conditional code. This is one more level of real-time debug using RT-MON in your application. 16

Real-Time vs. Stopmode Debug Advantages Code Composer Studio IDE and target are updated continuously User interrupts never halted Disadvantages Monitor uses % of CPU bandwidth Severe program errors must be resolved 15 In summary, the advantages of real-time mode debug versus stop mode debug are: - CCS IDE and the C24x DSP are updated continuously while your application interrupts never stop. Therefore you can tune your system parameters empirically on a live system. Disadvantages to real-time debug: - A % of the target DSP s CPU is consumed by the monitor code. Typically there is enough CPU time available to update the CCS IDE windows that are needed. - Severe program errors can disrupt the RT-MON communication. RT-MON is an interrupt-driven monitor system, so if your code goes into a continuous loop and never returns, RT-MON will never run. Verify your code is functional via stop mode debug before moving to real-time Debug. 17

18 RT-MON Resources Program INT 7 0x0E Data MSG_DATA MSG_CMND MSG_STAT MSG_CNTL 0x1C 0x1D 0x1E 0x1F Emulation Logic Message Passing C24x CPU Memory Interface RT-Mon Code 232 Words Page-0 Vars 0x60 (29 Words) INT 7 Full Context 16 The RT-MON software consumes very little memory. The monitor code is 232 words, which is only 0.7% of the LF2407 DSP s 32k Flash or 2.8% of the LF2402 DSP s 8k Flash. RT-MON uses the B2 RAM block at address 60h in data space. Only 29 words are used for RT-MON variables. This is 1.1% of the LF2407 DSP s or 5.3% of the LF2402 DSP s internal RAM.

Instrumenting the Target Application Add monitor code to project 17 Now that we understand the different operating modes of RT-MON and how to operate RT-MON from CCS IDE, let s look at how we integrate RT-MON into our application. A good place to start is by adding the RT-MON software into your application s CCS IDE Project. The ASM file C200MNRT.ASM is found in the C2000\Monitor sub-directory of your CCS IDE installation directory, which by default is tic2xx. 19

Instrumenting the Target Application Add support files to vector table C200MNRT.I RTVECS.h 18 Now that we have added the TI-supplied monitor code, let s modify the vector table to include the header file rtvecs.h. You can create this file from the C200Vecs.ASM file. That was installed with the CCS IDE installation. You can also copy this file from TI s website examples and from the RT-MON tutorial in your CCS IDE directory. Lastly we need to include C200MNRT.I, which defines the labels used in RTVECS.H. This file is also provided by TI as part of the CCS IDE installation. 20

Instrumenting the Target Application Add monitor sections to linker command file Program INT 7 Data Messaging 19 RT-MON sections: mon_main = Code mon_pge0 = Page-0 variables mon_rgst = ISR context RT-Mon Code Page-0 Vars Full Context Now that we have added the single RT-MON ASM file to our project and we have added the RT-MON ISR to our vectors table, we now need to link the RT-MON software to the memory on our C24x DSP. There are three RT-MON linker sections: - mon_main RT-MON code - mon_pge0 Page-0 variables - mon_rgst RT-MON ISR context save/restore Note that the variables are placed into B2, which is at address 60-7Fh. This Page-0 placement is a requirement of the RT-MON ISR software. 21

Instrumenting the Target Application Accurate context save/restore crucial Minimum = Status registers & ACC Indirect addressing recommended 20 The RT-MON interrupt (INT7) allows nested interrupts, allowing your application interrupts to continuously run. Therefore your application ISRs at a minimum need to do a context save and restore of the two status registers and the accumulator to maintain the context of RT-MON s ISR. In this slide we are showing this using indirect addressing. This is the recommended method over direct addressing since it allows the context save to be relative to current stack pointer position represented by AR1. AR1 is used by the C24x C compiler as the stack pointer. But even if you were writing your code in 100% ASM, it is still recommended to maintain a software stack and use AR1 as the stack pointer. 22

Instrumenting the Target Application Call MON_RT_CNFG From ASM Or from C 21 We know that to enter real-time mode we need to 1 st execute up to the label MON_GO. This label is defined in the monitor code that we added to our Code Composer Studio IDE project. The function that we call to setup and initialize the RT-MON code is MON_RT_CNFG. In this slide we are showing how to call this function from either ASM or C. From ASM you may want to consider using conditional assembler directives to give you the option to build your application with RT-MON or without it. For this example we are shown the parameter real_time as the assembler variable. When it is equal to 1, the RT-MON code will be called from the application. From C you can call MON_RT_CNFG by creating a C-accessible label. For this example we have chosen _RTMON_init. Note the leading underscore, allowing this label to be accessed from C. The prototype for this function will need to be defined as extern to give the C code visibility of the ASM function. Note also that we are initializing the RT-MON software AFTER we have initialized the DSP system and peripherals. For this example we show init() as the DSP system initialization and EvMgr_init() as the Event Manager initialization. 23

Instrumenting the Target Application Enable INT7 in IMR 22 The last step in your initialization code normally is to enable interrupts to start running. We see in this slide that if our assembler directive variable is equal to 1, the RT-MON ISR (INT7) will be enabled. This is also the point where we would enable our application interrupts, and for this example INT2 is enabled. 24

Real-Time From Flash Select ROM memory map from INIT.GEL Or from GEL menu 23 Now that we have looked at how to instrument RT-Mon into our application and how to run RT-MON from Code Composer Studio IDE and our target DSP, let s look at what we need to consider when running RT-MON out of Flash. Note that after our code is loaded into the DSP, whether this is by Code Composer Studio IDE loading RAM or the flash has been pre-loaded, our first steps are to reset the DSP and run to the label MON_GO. By executing the command go MON_GO essentially what we are instructing Code Composer Studio IDE to do is to place a software breakpoint at the label MON_GO and run to that breakpoint. Obviously when we are running from flash we can no longer use software breakpoints. What we can do is take advantage of the hardware breakpoint feature on the C24x DSP. This hardware breakpoint is a 16-bit register that is essentially an address comparator. When the program address bus is equal to the address in the hardware breakpoint register, the C24x DSP CPU will halt. We can use the hardware breakpoint to instruct the DSP to stop at to the label MON_GO. (Continued) 25

Real-Time From Flash Select ROM memory map from INIT.GEL Or from GEL menu 23 Real-Time From Flash Continued But to be able to use the hardware breakpoint we must first make sure that Code Composer Studio IDE using a ROM memory map. By doing so, this instructs Code Composer Studio IDE that software breakpoints can not be used and it enables the hardware breakpoint feature. You can configure Code Composer Studio IDE for a ROM memory map either through the GEL pull-down menu or you can edit the init.gel file that loads with your CCS IDE workspace. I recommend editing the init.gel file. 26

Real-Time From Flash Non-volatile memory requires H/W breakpoints Set H/W breakpoint at MON_GO 24 Then run to MON_GO To define a hardware breakpoint at the label MON_GO, simply open the Breakpoint window from CCS IDE s Debug pull-down menu. Select H/W Break from the Breakpoint Type list box and enter MON_GO into the Location box. Then click on Add and Ok. Now that we have added hardware breakpoint and we have defined CCS IDE to use a ROM memory map, we are ready to run our application in real time from Flash. After resetting and running the DSP, note in the Dis-Assembly Window that the code has halted at the label MON_GO. Note the purple line indicating a breakpoint is present at this address and as before, the yellow line indicates the position of the Program Counter. 27

Real-Time From Flash Disable H/W breakpoint at MON_GO 25 Ready to select real-time from menu and run (F5) It is good practice to disable the hardware breakpoint at this time since it is no longer need to stop at MON_GO. You can now use it to set a breakpoint in your non-isr code. Instead of deleting the hardware breakpoint definition at MON_GO, just disable it. Note in this slide the check-mark in the Breakpoint dialog box and the purple line in the Dis-Assembly Window are now gone, showing the breakpoint is disabled. When you save your CCS IDE workspace, it will save your breakpoint definitions. So you may want to consider having a Flashbased workspace that has the MON_GO breakpoint defined, ready to be enabled or disabled as needed. 28

Related Technical References Code Composer product line (CC 4.x) RT-MON Tutorial [Help -> General Help -> Tutorials->Real-Time Tutorial] RT-MON online help [Help -> General Help-> Real-Time Emulation ] RT-MON examples C2000 TI Foundation Library 26 You can find additional information on the RT-MON software in your CCS IDE help facility. There is an excellent tutorial to try that comes with your CCS IDE installation and is located in the directory: C:\tic2xx\C2000\tutorial\realtime. This tutorial will walk you through the steps required to run the example code in real time. Application examples that are instrumented with the RT-MON software are available from TI s website. These are excellent references to use to instrument your application with RT-MON. 29

RT-MON Drives Real-Time Debug Developers can transmit and receive data between a target application and a host application without stopping the processor RT-MON enables the viewing of live data via JTAG, while DSP runs from RAM or Flash RT-MON adds substantial value and powerful functionality to TI s toolset at no additional cost to users 27 We have seen today that RT-MON allows you to have your application running continuously and still have your CCS IDE windows updated. You have seen that you can use the real-time update to send data to the target, and it is an excellent way to tune your system parameters before placing them into a table in Flash or ROM. Using RT-MON while running from Flash provides an great way to do your final tuning of your system. All of this comes with Code Composer Studio IDE and the emulation logic on every C24x DSP allows it to work. 30

RT-MON Tips Allow RT-MON interrupt to run when debugging NMI (from illegal address) Add CLRC INTM to NMI ISR Add RT-MON after severe program errors are corrected Use RT-MON to tune your parameters Use aliases in INIT.CMD for productivity alias initrt, "reset;go MON_GO;realtime;go MON_RESET"; 28 1) NMIs commonly occur when an illegal address is generated. How can this happen? Forgetting an LDP or calculating the wrong address for a jump table, are common. When the NMI occurs, the Program Counter is vectored to 0x24. If you are using RT-MON, you need to allow nested interrupts in the NMI ISR. Otherwise the RT-MON ISR request will time out. By placing a BP after the CLRC INTM in the NMI ISR, you will halt the DSP in real time and within the NMI. You can now exit real time and correct the problem. 2) As with the NMI example, if your ISR code never returns the RT- MON IRQ will time out. So it is recommended to use stop-mode debug to get your code s basic functionality established before moving to real time. 3) By placing INIT.CMD into CCS IDE s my projects directory or in the location of where you have stored your CCS IDE workspace, CCS IDE will process this file every time you open the corresponding workspace. This allows you to combine multiple Command Window commands into a single command. 31

32 RT-MON Timing UISR1 IRQ RTM IRQ UISR1 IRQ UISR2 IRQ UISR1 IRQ UISR2 IRQ Back Ground RTM ISR 1 T L 3 4 5 2 2 UISR1 UISR2 Time 29 1) The RT-MON ISR only runs when the CPU is available. This is true when non-isr code is running or when another ISR allows nested interrupts and there are no other pending ISRs. 2) Note that user ISR1 is shown interrupting RT-MON s ISR. RT-MON s ISR is designed to allow nested ISRs, so that the application ISRs can continuously run. 3) Note there is a latency from point that UISR2 s IRQ was made and when UISR2 started to run. The UISR2 IRQ occurred during a lockout period, where the RT-MON is sending a single memory location to CCS IDE. This lock-out time is ~1 µs and occurs for every memory location that is transmitted. Therefore, minimizing the number of CCS IDE windows that are updated is important to manage the intrusiveness of the monitor to your application.

33 RT-MON Timing 30 Back Ground = Background S/W loop execution, i.e., non-isr (Interrupt Service Routine) RTM ISR = Real-time monitor ISR execution UISR1 = User ISR #1 execution UISR2 = User ISR #2 execution RTM IRQ = Real-time monitor interrupt request UISR1 IRQ = Interrupt request for user ISR #1 UISR2 IRQ = Interrupt request for user ISR #2 = User ISR & back ground lockout time, i.e., RTM ISR has full CPU control T L = Lockout time latency time Notes: 1 The RTM IRQ is only serviced during background code execution 2 User s code is locked-out during RTM s ISR context save/restore 3 A user s ISR may interrupt the RTM ISR during any non-lockout period 4 If a user s ISR request is coincident with the lockout period, a latency time is incurred A lockout period is also associated with every memory location updated in CCS window 5 The lockout latency time is in the order of 1-1.5 µs 6 The total piece-wise execution time of the RTM ISR varies based on the number of variables/windows being updated