This article will provide a guided step-by-step series of 'lessons' you can use to get started with basic debugging in an SSP ISDE.
1 Using this Article
Prerequisites: Review the Prerequisites before you start the debugging phase, to make sure you are ready.
Introduction: If you have satisfied the prerequisites, you can begin reading the below basic debugging Introduction that explains the key goals and objectives as well as the key topics covered in this article.
Lessons: A suggested step-by-step learning process is described in the basic debugging section, and new users are strongly advised to follow the steps as described. Experienced users could select only the topics where a ‘refresher’ is needed and skip the topics that have already been mastered, however, we recommend even experienced users do a quick scan through their mastered topics since this can be valuable in making sure the terminology we are using is consistent and familiar with your previous debugging environments.
What's Next?: Suggestions for follow-on lessons that build on what was learned.
Additional Resources: You can find out how to easily find additional debugging resources in this article.
2 Basic Debugging Introduction
Basic debugging covers the most common debugging features and techniques useful with the Synergy Platform. Once you have learned the topics associated with the lessons provided in this article you should be able to easily launch a debug session, verify that your target board is operating in debug mode, and find and correct most of the most common bugs hiding in your project.
Note that the techniques covered in these debugging articles assume that your code compiles correctly. If your code doesn’t compile correctly, we classify this as a code development error and these types of errors are covered in the Code Development related articles.
This article covers the main steps needed to create and launch a debug session and the basic debugging techniques useful for finding and fixing the most common errors in your code- such as logic errors, pointer errors, incorrect use of function parameters, and similar code related issues.
Review the below list to see if the topics you are interested in are covered in this article.
- Run and Launch the e2 studio Debugger
- Debug perspective in e2 studio- windows, buttons and commands
- Run and Launch the IAR C-SPY debugger
- Debugging features and techniques
- e2 studio
- IAR C-SPY
- General debugging techniques
3 Basic Debugging Lessons
The below lessons provide a lesson-based guided step-by-step process for mastering debugging with a Synergy Platform ISDE. Each lesson covers a set of related topics and usually takes around 5 to 10 minutes to complete. Use the following key to identify the resource used for each lesson topic:
PIoT: Prof IoT blogs on Renesas Rulz (Typically cover a single topic)
AN: Application Notes (Includes multiple topics- a topic list is often included in the description)
Vid: Videos (Can include multiple topics. If so, a topic list is included)
HoL: Hands-on Labs (Can include multiple topics. If so, a topic list is included)
Some of these lessons are specific to the ISDE being used- e2 studio or IAR Embedded Workbench for Renesas Synergy (IAR EW for RS)- and some are general enough to apply to both environments. Screen shots or specific illustrations of use may only be shown for one of the ISDEs, however these illustrations should be easy to apply to the other tool chain as well.
3.1 Introductions to Debugging with your Target ISDE
The following two lessons are specific to your target ISDE- e2 studio or IAR EW. Complete the appropriate lesson first so you are familiar with the debugging environment of your target ISDE.
3.1.1 Introduction to the e2 studio-based ISDE debugger
Use the following exercises to become familiar with the e2 studio-based debugging environment.
3.1.1.A: Initializing and using the e2 studio debugger (Topic list included below) Vid
- Build in Debug mode
- Launch a debug session
- Overview of each window in the debug perspective
- Overview of eclipse toolbar control buttons
- Overview of main toolbar control buttons
- Simple example of toolbar use
3.1.1.B: Debugging techniques within e2 studio (Topic list included below) Vid
- Trace Display
- Trace Events
- Breakpoint types and features
- Real-time Display
- Variable display
- Chart Display
- Visual Expressions
- Memory Display
- JPEG graphic
3.1.1.C: The SSP User's Manual (SSP UM) also includes information on some debug related topics. It will be useful to become familiar with the debugging resources available in the SSP UM. Read over Section 3.1.11 in the SSP UM (V1.3.2), Debugging the Project, and quickly review the following topics:
- Debug configuration
- Launching a debug session
- Using the RTOS resources view with a Synergy project (Advanced feature, covered in an upcoming lesson)
- Using the Thread-aware debug view (Advanced feature, covered in an upcoming lesson)
- Using the fault status view
- Using the Instruction Trace Macrocell (ITM) (Advanced feature, covered in an upcoming lesson)
3.1.2 Introduction to the IAR Embedded Workbench for Renesas Synergy C-SPY debugger
Use the following exercises to become familiar with the IAR EW RS-based debugging environment, C-SPY.
3.1.2.A: Debugging your application with IAR C-SPY- hands-on lab (Topic list included below) HoL
- Launch a debug session
- Overview of main toolbar control buttons
- Live watch
- Breakpoints, Conditional Breakpoints, Data Breakpoints
- Terminal IO, ITM Events
- Interrupt Logging
- Attach to running target
- ThreadX RTOS plug-in, Stack Analysis (Advanced feature, covered in an upcoming lesson)
3.1.2.B: The C-SPY User's Manual includes additional information on how to use C-SPY to debug projects using the IAR EW for RS tool flow. Review the C-SPY User's Manual, available here, and review the following topics:
- Getting started
- Executing your application
- Variables and expressions
- Breakpoints, Memory and Registers
- Trace, Profiling, and Code coverage (Advanced feature, covered in an upcoming lesson)
- Power debugging (Advanced feature, covered in an upcoming lesson)
- Error checking
3.2 Basic Debugging Techniques and Capabilities for SSP-based Projects
Once you are familiar with the operations within the debugger in your tool flow, use the following short lessons to learn more about basic debugging techniques applicable for SSP-based projects.
3.2.1 Basic debugging concepts
Use the following exercises to become familiar with basic debugging concepts.
3.2.1.A: Read and understand these Professor IoT posts describing key debugging concepts used in debugging all SSP-based projects.
A Bug Squashing Overview (Common debugging categories we will use in this article) PIoT
Understanding Error Codes (Determine error sources in SSP error codes) PIoT
Efficient Debugging using Breakpoints (Types of breakpoints in SSP and when to use them) PIoT
3.2.1.B: The SSP User's Manual includes a section that describes common error codes useful during debugging. Read over Section 6.1 in the SSP UM (V1.3.2), Common Error Codes. It includes a table showing all the common error codes returned from API calls. This is a useful reference when debugging, so make sure you can easily find it. For API specific Error Codes, refer to the appropriate API Reference Sections. For example, review Section 8.4.4, which shows the Return Values for the SF_Audio_Playback_HW_DAC_open API. Familiarize yourself with the location of these references which you may need during debugging.
3.2.1.C: For another description of the use of breakpoints, read over this Application Note:
Use of Breakpoints (Detailed description of how and when to use breakpoints in SSP-based designs) AN
3.2.2 Using print statement to assist in debugging
Use the following exercises to learn how to use printf statements to display information during code execution. This is one of the most common and useful debugging techniques.
3.2.2.A: Read and understand the following Professor IoT posts. They illustrate the use of printf statements to help with debugging.
Setting Up and Using Printf (Shows how to use this common technique in SSP) PIoT
Setting Up and Using Semi-Hosting (Shows how to use this common technique in SSP) PIoT
3.2.2.B: After you have done the above exercise, try a hands-on exercise to see this technique at work. Download and execute, on your target kit, an application program that uses a printf statement to display program results. One good example is the Application Program in the UART Module Guide: https://www.renesas.com/software/D6001595.html
3.2.2.C: As an additional hands-on exercise, edit the Blinky project to add a printf statement that prints "Blink" on the debug console when the LEDs are turned off. You can find the source code for Threaded Blinky here if you need a starting point.
3.2.3 Using assertions to identify bugs in your code
Use the following exercises to learn how to use assertions during debugging. Assertions not only help catch code errors, they can help zero-in on errors early in the execution cycle.
3.2.3.A: Read and understand the following Professor IoT posts. They illustrate the use of assertions and describe how they can help with debugging.
Catching Bugs using Assertions (Assertions and how to use them to find bugs in your code) PIoT
Setting Up and Using Assertions: (How to use assertions within SSP) PIoT
3.2.3.B: As a hands-on exercise, edit the Blinky project to add an assertion or two. Add one that you believe will be 'true' and on that will be 'false'. Print out the results of your assertions using your newly mastered printf statement. You can find the source code for Threaded Blinky here if you need a starting point.
3.2.4 Using MCU hardware capabilities for debugging
Use the following exercises to learn about MCU hardware resources used during debugging.
3.2.4.A: Read and understand the following Professor IoT articles describing Synergy MCU hardware features specifically used during debugging.
MCU Debugging Capabilities (Overview of MCU hardware features for debugging)
Getting Started with the Instruction Trace Macrocell (ITM) (Overview of ITM features)
Using printf with the ITM (How to set-up and when to use printf with the ITM)
4.0 What's Next?
Use these lessons to learn more about debugging Synergy Platform-based designs.
Advanced Debugging: Once all the basic debugging capabilities covered in this article have been mastered, we suggest you read the article on Advanced Debugging topics, such as debugging RTOS implementations, and debugging techniques for power, performance and memory footprint optimization.
Hardware Debugging: For debugging at the board, interface and chip level we suggest you read the article on Hardware Debugging.
5.0 Additional Resources
Basic debugging resources are being added periodically, so it is helpful to look over new material to see if it is applicable to your specific debugging interest. This Knowledge Base article details the locations for all published Synergy Platform related material.
Before you begin debugging you should have ordered a Synergy hardware kit, obtained a Synergy Gallery account, downloaded and installed a Synergy Platform ISDE, tested out your installation using a simple Synergy project like Blinky, learned how to create a simple SSP project and reviewed the basics of development with the Synergy platform. You should also have a copy of the SSP User’s Manual handy, and understand how to find helpful Synergy related resources and support. You can accomplish these prerequisites by following the instructions in these knowledge base articles.