1

Debugging on RX with IAR Embedded Workbench

Introduction

This lab will familiarize you with IAR Embedded Workbench for RX (EWRX) together with the Renesas RDKRX63N development board. EWRX has the ability to simulate generic RX cores, but for the purposes of this lab, we will utilize real hardware. Upon completion of this lab, you will have a better understanding of how EWRX functions so that you can debug your projects in an efficient way.

The lab is written for EWRX v2.40 but future versions of the tool will resemble the pictures contained therein. The easiest way to get started on a project is to use one of the provided example projects as base and this is what we will do also in this lab.

Lab Objectives

1. How to use complex data breakpoints2. How to do performance measurement3. How to use Trace and Profiling to inspect

the program flow and detect exceptions4. How to use C-SPY's RTOS awareness to

inspect internals of your RTOS

Lab Objectives

1. How to use complex data breakpoints2. How to do performance measurement3. How to use Trace and Profiling to inspect

the program flow and detect exceptions4. How to use C-SPY's RTOS awareness to

inspect internals of your RTOS

Lab Materials

Please verify you have the following materials at your lab station.

·A PC with IAR Embedded Workbench for RX v2.40 installed·A RDKRX63N development board with USB cable

Lab Materials

Please verify you have the following materials at your lab station.

·A PC with IAR Embedded Workbench for RX v2.40 installed·A RDKRX63N development board with USB cable

Time to Complete Lab

120 Minutes

Time to Complete Lab

120 Minutes

Skill Level

Intermediate. You should have at least basic knowledge of:

● Embedded development tools● The C or C++ programming language● Application development for embedded systems

Skill Level

Intermediate. You should have at least basic knowledge of:

● Embedded development tools● The C or C++ programming language● Application development for embedded systems

Revision 0.4

EWRX Training Lab

2

Part 1 – Get up and running

Exercise 1 - Executing an existing sample application on hardware.

1.) Let’s begin by connecting the hardware board to the computer via the USB cable. (The PC will supply power to the board).

RDKRX63N has an integrated J-Link emulator on board. (The IAR C-SPY debugger also supports the Renesas E1/E20 emulators)

2.) Start the Embedded Workbench for RX. Once EWRX is loaded, you will notice that the Information Center is visible. From the Information Center, you can view the release notes, user documentation, tutorials, and much more.

3.) Click EXAMPLE PROJECTS to browse the example project collection.

EWRX Training Lab

3

4.) Click RDKRX63N followed by Open project for the workspace called RDKRX63N board examples.

5.) You will be asked where to store the project; by default, workspaces and projects are stored in the ..\My Documents\IAR Embedded Workbench\ directory. Select this and you will get an own copy of the workspace with several example applications for RDKRX63N. The project ADC_One_Shot in the list to the left is in bold text which means this is the currently active project. Your screen should now look like this:

EWRX Training Lab

4

6.) You are now ready to download and debug our active application. Click the Download/Debug button on the toolbar.

7.) Before C-SPY is started for the first time in a new project, and when you change device, the hardware must be configured. This is why the Hardware Setup dialog box is shown:

8.) This dialog box is also available manually from the J-Link menu. We will use the default settings so click OK to continue.

If you are asked to update the emulator firmware, go ahead and do this.

EWRX Training Lab

5

9.) You might see a few windows pop up that indicate that the code is downloading to the device and then the device will execute the startup code and stop at the first instruction of main().

The Debug menu is available when C-SPY is running. The Debug menu providescommands for executing and debugging the source application. Most of the commandsare also available as icon buttons on the debug toolbar:

(A context menu is also available if you right-click in the source window)

10.) Execute the code by clicking the Go button (or F5). Follow the instructions on the LCD display.

We are now done with the “warm up”, how to get an application running on hardware.

(We think that you are familiar with source code debuggers already and will therefore not go through all the standard debugger features)

EWRX Training Lab

6

Part 2 – Complex data breakpoints

This exercise will make you familiar with C-SPY’s data breakpoint feature.

C-SPY lets you set various types of breakpoints in the application you are debugging, allowing you to stop at locations of particular interest. You can set a breakpoint at a code location to investigate whether your program logic is correct, or to get trace printouts. In addition to code breakpoints your are able to set a data breakpoint, to investigate how and when data changes.

Here is a summary of breakpoint types and numbers available for the different emulators:

(Detailed information about the different breakpoint types can be found in the C-SPY Debugging Guide)

EWRX Training Lab

7

RX devices have built-in hardware support for so called On-chip break which can be configured for different kind breaks. One of the is called Operand Access Event and this is what C-SPY utilizes for data breakpoints.

Exercise 2 - Different ways to acknowledge access to an array.

1.) Set the project DTC-Debug as active and start C-SPY.

2.) Open the source file dtc_demo.c, highlight the variable g_dtc_destination, right-click and select Set Data Breakpoint for ‘g_dtc_destination’ from the context menu.

3.) Click View>Breakpoints from the context menu to display the breakpoint window.4.) To inspect your breakpoint, right-click on it in the list and select Edit… from the context menu . Your screen should now look like this:

EWRX Training Lab

8

5.) Close the Edit breakpoint dialog box and click View>Memory from the context menu.

6.) Drag and drop the variable g_dtc_destination into the memory window.

Note that the end address of the array is 0x433 just like it says in the Edit breakpoint dialog box.

We will now run the example and observe accesses to our array.

7.) Execute the application from start (by clicking in the toolbar or by pressing F5).

8.) Follow the instruction on the LCD display that says press SW1.

The application should now halt in the following reset loop:

EWRX Training Lab

9

9.) Continue pressing Go (F5) until the loop is done and the application goes to idle mode.

10.) Stop the application.

What we just did was to cause a break for each access to any of the elements in our array. We will now change the breakpoint conditions a little.

11.) As the initialization code writes to our array, we need to disable the data breakpoint by un-checking it and reset the application so that we end up at main() again.

12.) Edit the breakpoint and set the Address condition to None.

13.) Enable the breakpoint, execute the application again and note the difference with our new setting.

Why does it break only once this time?

EWRX Training Lab

10

Exercise 3 - Use a data condition to break execution

1.) Open the source file dtc_demo_main.c, right-click on the variable g_sw1_pressed and select Set Data Breakpoint for ‘g_sw1_pressed’ from the context menu.

2.) Execute the application

Why does the application halt even though we haven’t pressed SW1?

3.) Edit the breakpoint and set Data Condition Read/Write to Write and Compared data to 1.

4.) Execute the application.

5.) This time, you actually need to press SW1 to make the application stop because this is what we specified as data condition.

EWRX Training Lab

11

By using trace, you can inspect the program flow up to a specific state, for instance an application crash, and use the trace data to locate the origin of the problem. Trace data can be useful for locating programming errors that have irregular symptoms and occur sporadically. In this section, we will implement a software bug and see how we can use the trace feature to find it during runtime.

Exercise 4 – Find a runtime error using trace

1.) Select the Power Modes example project, open the file r_switches.c in file group Switch and locate the following lines:

#pragma vector = VECT_ICU_IRQ9__interrupt void sw2_isr (void)

Edit these lines into:void sw2_isr (void)

Part 3 - Using trace to find bugs

EWRX Training Lab

12

2.) Build the application and start C-SPY.

3.) Choose J-link>Trace in the menu to show the trace panel.

4.) Click on the Power ( ) button to start recording trace information.

3.) Start execution and when the application is running, press Switch 2 on the board to enter into standby mode.

The program will now halt immediately.

Of course we know why, we changed an interrupt service routine (ISR) into a regular function. The application still compiles without problems but when Switch 2 is pressed, there is no service routine that takes care of the interrupt.

Let’s pretend that we don’t know what is causing the problem. How do we find why execution stops?

EWRX Training Lab

13

4.) Scroll down in the Trace window to the end of the recorded instructions.

5.) Enter trace Browse mode by double-clicking the last item in the Trace window (or click the Browse toolbar button). The selected item turns yellow and the source and disassembly windows will highlight the corresponding location. You can now move around in the trace data using the up and down arrow keys, or by scrolling and clicking; the source and Disassembly windows will be updated to show the corresponding location. This is like stepping backward and forward through the execution history.

6.) Now move backwards in the trace buffer from the bottom while being in browse mode. After a while you will see that abort()was called in a function starting at address 0xFFF02CC6. This is the so called default interrupt handler (default_handler) which address, the startup code populates the RX vector table with. This means that each interrupt source without an explicit ISR vector will end up executing the default interrupt handler.

7.) Choose View>Call Stack to open the call stack tree.

Which C function was last active when unhandled interrupt occured?

EWRX Training Lab

14

Part 4 - Using profiling to identify hot spots in your code

Function profiling can help you find the functions in your source code where the mosttime is spent during execution and perhaps give insight into how to rewrite it for better performance.

The profiler can use different mechanisms, or sources, to collect profiling information. Depending on the available hardware features, one or more of the sources can be usedfor profiling:• Trace (calls)

The full instruction trace is analyzed to determine all function calls and returns. When the collected instruction sequence is incomplete or discontinuous, the profiling information is less accurate.

• Trace (flat) / SamplingEach instruction in the full instruction trace or each PC sample is assigned to a corresponding function or code fragment, without regard to function calls or returns. This is most useful when the application does not exhibit normal call/return sequences, such as when you are using an RTOS, or when you are profiling code which does not have full debug information.

Exercise 5 – Run profiling on a simple code example

Let’s try the function profiler on the example project Dhrystone.

1.) Set the project as active and start C-SPY.

2.) Enable Function profiling by selecting Function profiler in the J-link menu in C-SPY.

3.) Click on the Power ( ) button to activate profiling.

4.) Press F5 to start the program.

After a few seconds, the result will show up on the board LCD.

5.) Pause debugging by clicking the Break button.

By default, the profiler will show how often a function is used based on samples (see Trace (flat) / Sampling above).

If you sort the profiler list according to the number of samples (by clicking the column header) you will see a few functions where the most time is spent.

EWRX Training Lab

15

Which function other than main()is used the most?

Let the program continue to run from here by pressing F5 again, you will see that the time share spent in main()is increasing.

Why is the time share spent in main()increasing continiously?

EWRX Training Lab

16

Exercise 5 – Using the profiler on instruction level in the Disassembly window

1.) Choose View>Disassembly to open the Disassembly window (if not already shown)

2.) Choose Instruction Profiling>Enable from the context menu that is available when you right-click in the left-hand margin of the Disassembly window. Also, make sure that the Show option on the context menu is selected, to display the profiling information.

3.) Start executing your application to collect the profiling information.

When the execution stops, for instance because the program exit is reached or a breakpoint is triggered, you can view instruction level profiling information in the left-hand margin of the window.

Note: As the J-link on-board does not offer full instruction trace, the profiling information for RDKRX63N will not be complete.

EWRX Training Lab

17

Part 5 - Using the performance analysis counterThe performance analysis feature allows you to measure a number of execution aspects in run-time without slowing down your MCU. Two 32-bit counters are available that can be used to measure two things at once or can be cascaded into one 64-bit counter.

What we can count is execution cycles, interrupts, instruction executions, exceptions and combinations thereof. The analysis can cover either the entire execution or execution between two breakpoints.

Exercise 6 – Cycle measurement

1.) Start C-SPY with the Dhrystone example from the previous exercise.2.) Choose J-link>Performance Analysis and open the Performance Analysis Settings dialog box either from the J-Link menu or from the toolbar in the Performance Analysis window.3.) Setup a single 64-bit counter to measure Execution cycle and check the option Display the cycle as a time span.4.) In the main() function, right click in the source window to open the context menu and set a Performance start 1 breakpoint just before the call to the function run_dry()and a Performance stop 1 breakpoint just after the call. Your screen should now look like this:

EWRX Training Lab

18

5.) Turn on the measurement with the power button ( ) in the Performance Analysis window.

The time measurement in the performance analysis function is simply the cycle count divided by clock frequency, it is not derived from an actual clock or a timer. Because of this, the correct operating frequency must be specified to get correct results.

6.) Set the operating frequency to 100MHz in the menu J-Link>Operating frequency. (Note that this doesn’t change the actual operating frequency)7.) Start execution and let it run until the Dhrystone result is shown in the LCD display.8.) Stop execution and it should now show in Performance Analysis window, time and the number cycles that were executed from call to return of the run_dry() function.

Exercise 7 – Cycle and instruction count measurement

1.) Start the debugger and set up the performance analysis counters to count both execution count (number of instructions) and execution cycles.

2.) Use these counters to analyze the performance of the two functions available in source file dhry_1.c listed in the table below.

Hint: Measurement works just as well during single stepping at C level and between regular breakpoints. Use the clear button ( ) in the toolbar to reset the counters.

Function name Cycles Count

Proc_8()

Proc_1()

EWRX Training Lab

19

Exercise 8 – Interrupt cycle and interrupt count measurement

Let’s look at another example of performance analysis where we will use the Performance analysis counters to count Interrupt cycles and Interrupt count. We will use the GPIO_IRQ example which uses external interrupt from switch 1 and 2 to detect when the buttons are pressed and released

1.) Start C-SPY with the GPIO_IRQ example.

2.) Open the Performance Analysis window and enable measurement.

3.) Set up the performance analysis counters to count interrupt cycles and interrupt count.

4.) Measure and try to find the worst case for the number of cycles used for interrupt processing for one button press + release in series for switch 1 and switch 2. Reset the debugger between every try to make sure that the ISR takes the same path every time.

You will probably see that the number of interrupts/cycles for a single keypress varies a little from time to time. This can have more than one explanation but what is the most likely cause?

How did the developer try to solve the problem above, in this example program?(The interrupt handlers can be found in switches.c)

EWRX Training Lab

20

Part 6 - Introduction to the ThreadX RTOS plugin for C-SPYThe ThreadX plugin for the ThreadX RTOS simplifies debugging of real-time applications with useful multithread-specific features. It adds extra features to the C-SPY debugging interface that are specific for the ThreadX RTOS.

Plugin features• Thread-specific stepping panel• Thread-specific breakpoints• Thread List window and per-thread C-SPY windows for registers etc.• ThreadX OS resource information windows• Execution profiling (not in demo)• Performance metrics (not in demo)

EWRX Training Lab

21

Exercise 9 – Using thread specific breakpoints

An important features of the plugin is the ability to set thread-specific breakpoints and to allow stepping in a thread just as easy as in a single-threaded application.

(The thread-specific stepping panel is highlighted in this picture)

Let’s add some shared code in this application to better show how these features can be used.

1.) Next to the example workspace you opened in Exercise 1 there is a workspace called Express Logic's ThreadX Demo. Open this workspace via the Information Center (available from the Help menu) and link to RDKRX63N.

2.) Add the following shared code after the existing #include statements in source file demo_threadx.c:

#include "stdio.h"void sharedFunction(ULONG thread_input){ printf("In thread %lu\n", thread_input);}

EWRX Training Lab

22

Each thread consists of an entry function (some entry functions are shared between multiple threads) and in it an infinite loop which is what the thread executes.

3.) In this loop, add the following in the while(1) loop of each tasks entry function in demo_threadx.c so that we make some calls to our new shared function:

sharedFunction(thread_input);

EWRX Training Lab

23

4.) Download and start debugging the application and choose View>Terminal I/O.

5.) Begin by setting a regular breakpoint at the closing bracket of our sharedFunction() (so that printf() has been executed) and press F5 to start.

6.) When the debugger breaks in our function, choose ThreadX>Thread List in the menu to show the list of threads. In the list, you will see a green arrow pointing to the current thread and in the state column you’ll see that it is running.

7.) Press F5 again to get to the breakpoint again.

A new thread is now running and if you open the the Terminal I/O window via the View menu, you will see the printouts from each thread. This shows that that a traditional breakpoint will stop the program regardless of which thread is running.

8.) To set a thread specific breakpoint, right click on the breakpoint that is already set and select Edit Breakpoint in the context menu.

9.) Click the Condition true radio button (even if already selected) followed by clicking the Task button.

10.) Select in which specific thread you wish the breakpoint to be active.

EWRX Training Lab

24

11.) Now that we’ve changed our breakpoint to a thread specific one, press F5 again and look in the task list.

You should now see in the Terminal I/O window that only the specific thread that you selected for the breakpoint is active and the other threads do not stop.

Thread specific stepping

As shown in a previous screenshot, there is a thread-specific stepping panel available in the toolbar. The difference between global (normal) stepping and thread-specific is that when you step within your thread, another thread could be scheduled-in before you reach your expected next statement. This thread-switch may cause the new thread hitting one of the breakpoints before the original thread does. It may then appear as you have performed a normal step, but you are actually watching another thread.

EWRX Training Lab

25

Thread List By selecting (double clicking) a thread in the Thread List window, we can look at thread specific information in regular C-SPY windows like Watch, Locals, Register, Call Stack, Source, Disassembly, etc, from the point of view of the thread in question. A thread selected in this way is indicated in the Thread window by a different color. For example, even though a thread might not be running, we can still see its register contents in the Register window. Changes in the C-SPY windows between stepping, hitting breakpoints, etc, are marked with red.

Information, metrics, profiling, etc.Other information windows provided by the ThreadX plugin show statistics about the OS resources like queues, semaphores, mutexes, shared memory pools, software timers, event flags, etc. This can be helpful for debugging thread interaction-related issues like deadlocks and scheduling problems in general.

Execution Profile enables features for measuring RTOSperformance with execution profiling and performance metrics. (This is not available in the evaluation version used in this demo)

ThreadX plugin information and statistics windowsThe current state of the ThreadX OS and your threads can be inspected with the various windows, which you can show by selecting them from the ThreadX menu.