ETM Lab: Cortex™-M3 Training Fujitsu MB9BF500: Keil MCB9BF500 eval board Summer 2010

Version 0.8

by Robert Boys,

[email protected]

Introduction: The purpose of this lab is to introduce you to the art of debugging using ETM (Embedded Trace Macrocell) available in many Cortex™-M3 processors. We will be using the ARM® Keil™ MDK toolkit featuring μVision® with a Keil MCB9BF500 evaluation board using either a MB9BF500 and a ULINKpro USB to JTAG/SWD adapter as pictured below. ETM provides all the program counter values providing a history of instructions executed. Using ETM along with Serial Wire Viewer (SWV) provides exceptional debugging. You can find bugs nearly impossible to find with regular stop and go debugging. SWV provides real-time (no CPU cycles stolen) display of memory and variables, data reads and writes, exception events and program counter sampling plus some CPU event counters. ETM adds all the program counter values and is controlled with triggers and filters. SWV is supported by the Keil ULINK2, ULINK-ME and Segger J-Link adapters. ETM Trace is supported with either the ULINKpro, the Signum JtagJetTrace or Segger J-Trace (under development). Keil MDK comes in an evaluation version that limits code and data size to 32 Kbytes. Nearly all Keil examples will compile within this 32K limit. The addition of a license number will turn it into the full, unrestricted version. Contact Keil sales for a temporary full version license if you need to evaluate at greater than 32K. Keil also provides RL-ARM. This package includes the source files for the RTX RTOS, a TCP/IP stack, CAN drivers, a Flash file system and USB drivers.

Why Use Keil MDK ? MDK provides these features particularly suited forCortex-M3 users: ARM® Keil™ MDK toolkit. 1. µVision IDE with Integrated Debugger, Flash programmer and the RealView ARM compiler. 2. A full feature RTOS is included with MDK: RTX is a Keil product. 3. Serial Wire Viewer trace capability is included. 4. ETM Trace support with ULINKpro. 5. RTX Kernel Awareness window. It is updated in real-time 6. Choice of USB adapters: ULINK2, ULINK-ME, ULINKpro. 7. Kernel Awareness for Keil RTX, CMX, Quadros and Micrium. All RTOSs will compile with MDK. 8. Keil Technical Support is included for one year. This helps you get your project completed faster. This document details these features: 1.

ETM trace with the Keil ULINKpro.

ETM Trace: ETM (Embedded Trace Macrocell) adds all the program counter (PC) values to SWV. ETM is especially useful in finding PC related bugs such as classic “in the weeds”, spurious writes and stack problems. AN ETM emulator such as the Keil UKLINKpro (pictured) also provides SWV and very fast Flash programming times. UKLINKpro also provides an additional trace to source/assembly link in the μVision source windows.

1 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com

Software Installation: This document was written for Keil MDK 4.12 which contains µVision 4. MDK 4.12 is available on the Keil website. Do not confuse µVision4 with MDK 4.0. The number “4” is a coincidence. You will need an initialization file called etm.ini. Future versions of MDK will contain this file or one similar. It activates the 4 bit ETM Trace Port. Place this file in C:\Keil\ARM\Boards\Keil\MCB9BF500. If you have a previous version of MDK, do not uninstall it; just install the new version on top. For a clean install of the examples, erase your project directories as well as those in C:\Keil\ARM\Boards. This is where the examples are stored. You can use the evaluation version of MDK for these exercises. A ULINKpro is needed to collect and display ETM frames. Index:

1. Blinky example using the Keil MCB9BF500 board and ULINKpro

3

2. Configuring the Trace

4

3. Viewing the ETM Trace Records

4

4. Experimenting with ETM Trace !

5

5. Displaying Initialization Sequences

6

6. In-the-weeds Example

7

7. Code Coverage

8

8. Performance Analyzer

9

9. Execution profiling

10

10. Keil Products and contact information

11

2 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com

1) Blinky example program using the Keil MCB9BF500 and ULINKpro: Now we will connect up a Keil MDK development system using real target hardware and a ULINKpro. These examples will run on the MCB9BF500 which uses a MB9BF500 processor. 1.

Connect the equipment as pictured on page 1. Power the MCB9BF500 with a regular USB cable.

2.

Start µVision by clicking on its desktop icon.

1.

Select Project/Open Project.

2.

Open the file C:\Keil\ARM\Boards\Keil\MCB9BF500\Blinky\Blinky.uvproj.

3.

Blinky is configured by default to use a ULINK2 or ULINK-ME. We will configure it to run with a ULINLKpro.

TIP: A project Blinky_ULp will probably be included a future version of MDK and will be preconfigured for the ULINKpro but we will learn how to configure Blinky ourselves. 4.

Copy the file etm.ini into the Fujitsu project directory. This will be in the C:\Keil\ARM\Boards\Keil\MCB9BF500\ directory. Use Windows Explore to do this. You can place in the Blinky directory if you prefer.

5.

Open the Options for Target by clicking on its icon.

6.

Configure the µVision Flash programmer: Click on the Utilities tab. Select ULINK Pro Cortex Debugger.

7.

Click on Settings and remove any algorithms if present. Add the MB9BF50x 512kB Flash programming algorithm. Set RAM start to 0x2000_0000 as shown:

8.

Click on OK once to return to the Options for Target window.

TIP: Checking Update target before Debugging programs the Flash when you enter debug mode. Otherwise you must manually program the flash with its icon each time you rebuild your source files. 9.

Configure the Debugger for ULINKpro: Select the Debug tab and change USE: from ULINK Cortex Debugger to ULINK Pro Cortex Debugger.

10. In the Initialization file box click on the Browse button

and select etm.ini from the MB9BF500 directory.

11. Your window corner will look like this: 12. Click on the Settings: box beside where you selected ULINK Pro Cortex …. 13. The window below opens up. 14. You must have an entry called ARM CoreSight SW-DP in the large box labeled SW Device. This indicates you have connection to the CoreSight debug module inside the ARM processor. Urgent TIP: If you don’t see ARM CoreSight SW-DP in this window and instead get an error message or device not found or JTAG – stop right now and fix this. This section must work before you can continue any debugging. Make sure the board is properly powered and the ULINKpro is properly connected. Try re-powering the board and the ULINKpro. 15. Make sure SWJ is checked and Port: is set to SW and not JTAG. JTAG must NOT be selected. This must be set to SW (SWD = Serial Wire Debug). 16. Do not click on OK yet. TIP: The Serial No. box is where you select multiple ULINK devices connected to your PC, one at a time. At this point you have selected the ULINKpro as your choice of adapter for both debugging and Flash programming. Your ULINKpro has successfully made connection to the CoreSight debug module. On the next page, we will configure the Trace: both SWV and ETM.

3 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com

2) Configuring the Trace: 1.

Select the Trace tab. This window opens up:

2.

Set Core Clock to 80 MHz.

3.

Select Sync Trace Port with 4-bit Data in Trace Port.

4.

Select both Trace Enable boxes.

5.

Deselect ITM Port 0. (turns off Debug Viewer):

6.

Your final screen will look like this:

7.

No SWV options are selected.

8.

This means all we will see in the instruction Trace window are ETM frames.

9.

Click OK twice to return to the main menu.

10. Select File/Save All. 11. Compile the source files by clicking on the Build icon.

.

17. Program the MB9BF500 flash by clicking on the Load icon: 18. Enter the Debug mode by clicking on the Debug icon. Remove SWV activity:

Progress will be indicated in the Output Window.

Select OK if the Evaluation Mode box appears.

19. If you are using Blinky from a previous exercise and have a Watchpoint active the program will stop. Open Debug/Breakpoints or press Ctrl-B. Use the Kill All button to remove any Watchpoints and Breakpoints. 20. Open the Logic Analyzer (LA) and Select Setup… and click on Kill All. Click on Close. 21. Click on the RUN icon.

Note: you stop the program with the STOP icon.

3 LEDs on the MCB9BF500 will now blink at a speed according to the setting of the blue pot P7. Now you know how to configure the Trace, compile a program, load it into Flash and run it and stop it. Important Note: ETM Trace Port Pins Sharing:

ETM Trace0 through Trace3 are shared with on GPIO ports P05 through P08. TraceCLK (the trace clock) is on Port P09. The JTAG/SWD and SWO pins are on P00 through P04. There are other peripheral pins shared with P05 through P09. These are not useable when using ETM and/or JTAG/SWD and SWO. You must take this into consideration when designing your hardware and assigning pins to avoid conflicts.

3) Viewing the ETM Trace Records: 1.

Open the Instruction Trace window by selecting it from the main menu:

2.

ETM Trace frames will now be visible whether the program is running or not like this:

4 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com

4) Experimenting with ETM Trace !

Note: IT = Instruction Trace window.

Note: some of the addresses may be slightly different and you may have to compensate. 1.

Stop the program if it is running.

Stop Processing captured trace if it is taking a long time.

2.

Clear the Instruction Trace (IT) window by leaving and re-entering Debug mode.

3.

The Blinky will run to main() and stop. This is because Options for Target/Debug/Run to main() is selected. The window below will be visible: (I have adjusted the columns from default)

4.

Open the CPU register window by selecting View/Register Window if necessary.

5.

Note the PC = 0x0000_03F4 in the register window. This points to the next instruction to be executed. The IT window shows this BL.W was executed. This is not true and will be fixed in a future version of µVision. (maybe)

6.

Select View/Disassembly Window if not already open. Select its tab if it is open. (beside the Instruction Trace tab)

7.

The yellow arrow in the disassembly window shows the PC at 0x03F4. Scroll up a few lines and the preceding instruction is at 0x3F2 and is a POP instruction. Was this instruction executed before MOVS at 0x3F4 ?

8.

If the POP was executed – where did it go and how did it get back to 0x3F4 ? When does the BLT at 3F0 get executed ? What is the POP doing where it is ? ETM trace tells you.

9.

Examining the IT window above, the instruction executed before was at 0x10A BX. It was not the POP.

10. Double click on 0x10A in IT window and you will be taken to this in the Disassembly window which shows it as part of _main_init. TIP: The disassembly window works best when scrolling down. Scrolling up might miss some instructions due to ELF quirks. Just scroll up and then down a bit to correct the display. 11. Right click and Show Disassembly at Address at 0x3F0 to get back to where you were before. 12. Set breakpoints at addresses 0x3F0 and 0x3F2 by double-clicking in the left margin in the disassembly window. 13. Click on RUN. 14. Program stops at 0x3F0 and is shown in the IT window. Click on RUN a few more times and you are in a loop. 15. Note the cyan block to the left of the BLT instruction at 0x3F0 in the disassembly window. (this is Code Coverage) 16. Remove the breakpoint at 0x3F0 in the disassembly window and click on RUN. 17. Confirm the program next goes to 0x3F2 POP. The previous instruction recorded is BLT at 0x3F0. 18. BLT displays as *BLT which indicates the branch was not taken. Note the cyan block at 0x3F0 is now green indicating all possibilities have been executed. 5 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com

Some more fun…. 1.

Every time you click RUN, the program executes and stops again on the POP at 0x3F2.

2.

Click the Single Step icon

3.

Click RESET.

4.

This is because you inadvertently turned ETM off by resetting the processor.

5.

and note the trace appends every instruction.

Click on RUN and STOP and/or Single Step and note the trace no longer updates.

etm.ini activates the Trace Port and is activated every time you enter debug mode. You must rerun etm.ini.

6.

Select View/Command to open the Command window if not already open.

7.

Type DebugSetup() in the Command window and Enter: TIP: after once you can use the up arrow to select it again.

8.

Click on RUN and the program runs to the breakpoint at 0x3F2.

9.

Confirm the trace is working again. Try single stepping.

5) Displaying Initialization Sequences: Some programs execute an initialization sequence normally to initialize peripherals. While it is possible to single-step through some parts of this code, some instructions will modify the processor operation enough to crash the debugger or the instructions must be executed as one block with no interruptions. We will demonstrate how to trace this code. ETM trace does this automatically. 1.

Remove any breakpoints you set. Ctrl-B and Kill All or Debug/Breakpoints and Kill All.

2.

Exit and reenter Debug mode. The program runs to main() and the ETM is displayed as demonstrated before.

3.

Note the last frame in the Instruction Trace window (IT) is as before: 0x3F4 MOVS.

4.

Scroll all the way to the top of the IT window and see the LDR instruction at 0x0000_0114.

5.

This is the start of the Keil initialization sequence at RESET and it is recorded in the trace buffer for you to examine.

6.

Open Memory 1 window if necessary (View/Memory Windows/Memory 1) or click on its tab if it is already present.

7.

Enter 0 in the address box. Right click in the window and select unsigned long. Memory 1 will look like this:

8.

Address 0 contains the initial Stack Pointer. 0x2000_0228.

9.

Address 4 contain the initial Program Counter ! The same LDR at 0x114. Remember to subtract 1 from 0x0000_0115 to get 0x0000_0114.

10. Click Step

and note the IT window correctly appends.

11. If you unselect Run to main() in the Options For Target window in the Debug tab: you can successfully single step all the way to the MOVS at 0x3F0 and the program seems to run correctly. But remember the ability of ETM to record all the instructions in a large block for those instances where you are unable to single step. This is the only way (other than a simulator) to debug this type of code. This can also happen during PLL and clock configuration. Use the ETM trace for such debugging. TIP: Stepping through initialization sequences can sometimes be very tricky. Processor settings are changed and it is easy for µVision to get lost. Such program sequences that can’t be stepped through are normally recorded in the ETM trace. What happened can be determined from this accurate record. This is how such code sequences are debugged. Without ETM trace, certain problems can be extremely difficult and time consuming to solve. Sometimes asynchronous exceptions can also trip you up when single stepping. ETM records all such program branches. 6 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com

6) In-the-Weeds Example A common problem facing developers is when something happens to their program and the processor goes wild, overwriting potentially valuable clues and in the case of a Cortex-M3, end up at the Hard-Fault vector which, by default, is a Branch to itself. If you are fortunate, the stack is intact and you can derive information where the program was when the crash happened. uVision has a Call Stack window to help you. But what if it isn’t intact ? Or the problem occurred a long time before in a function no longer on the stack ? or many other scenarios ? This is what ETM is most valuable for. And it is really easy to setup and use. We will create a hard fault by executing a POP out of order and demonstrate this is recorded in the Instruction Trace window. 1.

Use the same Blinky as the previous example. Exit and re-enter Debug mode. The Instruction Trace (IT) will display code as demonstrated before.

2.

Remember the POP instruction at 0x3F2 in the previous example ? We will use it to crash Blinky.

3.

Scroll down up the Disassembly window to the POP instruction at 0x3F2.

4.

Right click on this POP and select Set Program Counter. This POP will be executed without a prerequisite PUSH.

5.

Click on RUN and the program will stop as shown by the LEDs stopping blinking.

6.

Click on STOP. The PC is on the Hard Fault Handler at 0x011E as shown here: The IT window will show many trace frames.

7.

Set a breakpoint at 0x011E by double-clicking in the left margin in the disassembly window as shown here:

8.

Click on RESET and type DebugSetup() and g, main in the Command window.

9.

Scroll up to the POP near 0x3F2 and right-click and set the Program Counter to this instruction.

10. Click on RUN and the program will hit the breakpoint at the Hard fault Handler. 11. The IT window will now display the offending POP instruction and the Hard fault Handler. This is a very simple example but it is clear to see that all instructions executed before the POP would be recorded to help you track down the bug. 12. If you set the PC to an instruction before the POP you will see more trace frames as the program executes towards the POP. Address 0x03E6 MOV R0,R3 seems to work well. Repeat starting at Step 8 to try this address.

What else can you find with techniques like this ? Array and pointer overruns. Bad data written by “who knows what function”. Data read or written to/from places you do not know about. TIP: If you are expecting an error that is intermittent, it can be a good idea to set a breakpoint on the Exception Handler for the type of error you expect. When the error happens, the trace will have a recording without millions of error handler code. 7 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com

7) Code Coverage: Code Coverage tells if what instructions were executed or not. This includes partial executions in the case of branches. This is often a certification requirement for safety critical products such as the FDA and FAA. For general good engineering practices, it is beneficial to make sure all your code has been executed and tested. Code Coverage is easy and complete with ETM Trace. Code Coverage is always active if ETM is. 1.

Start µVision and Blinky. ETM trace must be properly configured.

2.

Enter Debug mode and make sure the disassembly window is open. Click on RUN.

3.

If a window is in focus, Code Coverage information will be displayed as shown below: scroll up if necessary.

4.

Note the source windows also contain Code Coverage information.

Legend: at address: A. 0x592 – branch never taken. B. 0x594 – LDR executed. C. 0x59C – branch always taken. D. 0x59E – NOP never executed. E. Line 1760 – no assembly exists.

Shown below is the legend to the colour blocks. They indicate which assembly instructions have been executed. This can be saved in a file to make a report. See Help. 1. 2. 3. 4. 5. 6. 7.

Green: this assembly instruction was executed. Gray: assembly instruction located here was not executed. See Line 839. Orange: a Branch was not taken. Only half the possibilities were exercised. Cyan: a Branch was taken. Only half the possibilities were exercised. Light Gray: no assembly instruction exists at this point. Breakpoint is set here. Points to the next instruction to be executed.

8.

Open View/Analysis Windows/Code Coverage. The window below opens up.

9.

If all zeroes are reported, click on the Update box.

10. This window gives you a start on where to look for unexecuted instructions. TIP: You need ETM trace to display Code Coverage but it is also available in the µVision simulator. TIP: The Disassembly widow updates while the program is running. The Source windows update when you click in them.

8 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com

8) Performance Analysis: This ETM feature tells you where your program is spending its time. Often the results can be quite illumination and surprising….and sometimes shocking. 1.

With Blinky running (or it can be stopped), open View/Analysis Windows/ Performance Analysis.

2.

The window below will open up.

3.

Expand some of the modules if necessary.

4.

Note the entries are updated while Blinky is running. This is because of the ETM trace live update.

Note: The Reset button is not active at this time. Soon. TIP: You need ETM trace to display Performance Analyzer but it is also available in the µVision simulator.

5.

Stop Blinky. Exit and re-enter Debug mode. The program will run to main().

6.

Note the display of the Performance Analyzer as shown below: this is it has run to main() only. Expand various modules and functions to see various graphs.

7.

Click on RUN and watch it change. Very cool.

9 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com

9) Execution Profiling: 1.

While Blinky is running (or it can be stopped), select Debug/Execution Profiling/Show Time.

2.

If necessary, open up both the Disassembly and Blinky.c windows as shown here:

3.

The yellow area will open up.

4.

Total time is displayed.

5.

Disassembly updates always.

6.

Source when you click in it.

7.

Hover a mouse over a time and see total time, average time and number of calls. See the screen below.

8.

Outlining: You can mark (collapse) a section to add time.

9.

On the While(1) loop shown here: use your cursor to block it.

10. Right-click on this block and select Outlining/Collapse Section. 11. You will get a screen as below: Click on the + and it will expand.

12. Select Debug/Execution Profiling/Show Calls and a window similar to this one will open up:

Using Execution profiling will provide you with important information on how efficiently your program is running. All the features described use ETM trace feature as found on the Fujitsu MB9BF500 family of ARM Cortex-M3 processors. The End (for now) 10 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com

10) Keil Products: Keil Microcontroller Development Kit (MDK-ARM™) 

MDK with included RTX RTOS – $4,895 (MDK has a great simulator)



MDK-ARM-B: 256K code limit, no RTOS – $2,895

Keil Real Time Library (RL-ARM™) 

RTX sources, Flash File, TCP/IP, CAN, USB driver libraries - $4,195

USB-JTAG adapter (for Flash programming too) 

ULINK2 - $395 (ULINK2 and ME - SWV only – no ETM)



ULINK-ME – sold only with a board by Keil or OEM.



ULINK-Pro - $1,395 – Cortex-Mx SWV & ETM trace

Note: USA prices. Contact [email protected] for pricing in other countries. For the entire Keil catalog see www.keil.com or contact Keil or your local distributor.

For more information: Keil Sales In USA: [email protected] or 800-348-8051. Outside the US: [email protected] Keil Technical Support in USA: [email protected] or 800-348-8051. Outside the US: [email protected]. For comments please email [email protected]. For the latest version of this document, contact the author, Keil Technical support or www.keil.com. For Signum Systems: www.signum.com and Segger: www.segger.com.

11 Cortex-M3 ETM Lab withKeil µVision

Copyright © 2010 ARM Ltd. All rights reserved

www.keil.com