This article will provide a guided step-by-step series of 'lessons' you can use to get started with intermediate level debugging features and techniques when using an SSP ISDE.
1 Using this Article
Prerequisites: Review the Prerequisites before you start these lessons, to make sure you are ready.
Introduction: If you have satisfied the prerequisites, you can begin reading the below Intermediate 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 Intermediate 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 additional resources to help all your Synergy Platform development efforts.
2 Intermediate Debugging Introduction
Intermediate debugging covers the common debugging features and techniques useful with more complex designs for the Synergy Platform. Once you have learned the topics associated with the lessons provided in this article you should be able to use more advanced debugging techniques to find and correct difficult 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 techniques generally associated with the use of specialized MCU hardware available for debugging more complex designs. Review the below list to see if the topics you are interested in are covered in this article.
- Debugging Review- breakpoints, trace and display
- Using trace capabilities to simplify debugging- Embedded Trace Macrocell, Percepio Tracealyzer
- Intermediate debugging- views, debug virtual console, Python scripting, stack usage
- Intermediate debugging for RTOS applications- overview, RTOS resources view, IAR analysis tools
- Using TraceX for debugging- introduction, examples, thread status, performance analysis
3 Intermediate 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 20 to 30 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 Debugging review
Use the following exercises to review important debugging techniques that will be useful for intermediate debugging lessons.
3.1.A: Debugging techniques within e2 studio (Topic list included below) Vid
- Trace Display and Trace Events
- Breakpoint types and features
- Real-time Display
- Visual Expressions
- Memory Display
3.1.B: Read and understand the following Professor IoT articles describing debugging techniques useful for intermediate debugging lessons.
Efficient Debugging using Breakpoints (Types of breakpoints in SSP and when to use them) PIoT
Setting Up and Using Printf (Shows how to use this common technique in SSP) PIoT
3.1.C: The SSP User's Manual, SSP UM, includes useful debugging information you should be familiar with. Review Section 126.96.36.199 on Debugging the Project. In particular, look over the below sections that will be helpful in future intermediate debugging lessons.
- Using the RTOS Resources View with a Synergy project
- Using the Tread-aware Debug View
- Using the Fault Status View
- Using the Instrumentation Trace Macrocell (ITM)
Review Section 6.1 on 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 Using Trace capabilities to simplify debugging
Use the following exercises to learn about MCU hardware resources and how they are used to make it easier to find some of the more complex bugs.
3.2.A: Read and understand the following Professor IoT articles describing Synergy MCU hardware features specifically used to help with debugging.
MCU Debugging Capabilities (Overview of MCU hardware features for debugging- a review) PIoT
Debugging using the Embedded Trace Macrocell (Overview of ARM Cortex-M4 advanced debugging hardware) PIoT
Configuring a Synergy project for ETM Tracing (Illustrates how to use configure ETM tracing with Blinkly) PIoT
Examining and Using ETM Trace Data (Illustrates several useful trace data views with the EMT) PIoT
3.2.B: Renesas has third party providers that support trace-based debugging capabilities. Use the below exercises to see how these tools can further simplify debugging of Synergy projects.
Tracing with Percepio's Tracealyzer (Generate trace data using the Percepio Tracealyzer tool) PIoT
Tracing with Percepio's Tracealyzer (Visualization trace data using the Percepio Tracealyzer tool) PIoT
The Percepio Tracealyzer is available from the Synergy Solutions Gallery here. As a hands-on exercise, download and install Tracealyzer. You will find the manual in Program Files (x86)/Percepio/Tracealyzer/manual. Click on Index and read the Introduction. In the Example Uses section you will find a Getting Started link. Click on this and you will find the Getting Started page on the Percepio web site. Observe the additional resources and explore any that are of keen interest. HoL
3.2.C: As a hands-on exercise bring up Tracealyzer and follow along with the RTOS 101 posts available on the percepio Tracealyzer getting Started page here. Pay particular attention to how to analyze tasks, semaphores and queues since these fundamental building blocks you will have in virtually every Synergy project. HoL
3.3 Intermediate debugging tips and techniques
Some of the most useful intermediate debugging techniques utilize familiar debugging capabilities, just in ways you might not be aware of. These lessons expand on some of the techniques already covered, but illustrate their use to find more complex bugs.
3.3.A: Read and understand the following exercises that expand on debugging techniques and illustrate more in depth uses.
Data Visualization (Observing data in convenient forms during debugging) PIoT
The e2 studio IDE User's Manual has detailed descriptions of some of the key capabilities useful for finding complex bugs. Read over the sections in Chapter 5 covering the following topics. Return to these sections when you can't find pesky bugs that can't be found with the basic Breakpoint and Printf based techniques.
- Expressions view
- Registers view
- Memory view
- Variable view
- Eventpoints view
3.3.B: The e2 studio Help System provides a convenient method for accessing debugging related information, tips and techniques. Simply Click on the Help pull down from the top function bar in e2 studio and select Help Contents. You can type a search criteria to see a list of all related topics. For example, type in "Debug" and you will et over 200 matches. Quickly scroll through the topics to get a flavor for the types of information available. Note that the results are not Synergy specific, so you will probably want to skip over topics that are clearly targeted for other MCUs. Remember this Help capability however when you forget how to set a specific preference, where to find a particular view or how to use a feature. As a hands-on exercise find the following topics and read them over. Are they applicable to intermediate level debugging?
- Using the Renesas Debug Virtual Console
- Python Scripting
- Adding Expressions
As a follow-up, search for "Debug Memory" topics. Do the topics that come up match what you would expect? Scan through them and look at a couple of the ones that are of most interest to you. HoL
3.3.C: Sometimes you have a bug that just doesn't want to show itself. After you have tried all the tricks and techniques you can think of, and it is still elusive, what can you do? One possibility is to post the issue on the Renesas Rulz Synergy Forum web site. It's possible someone in the community knows of a technique you can use to zero in on your pesky bug. The Renesas Rulz Synergy Forum is available here: https://renesasrulz.com/synergy/f/synergy---forum. Look over some recent posts to see the types of issues that get posted and the type of replies that are generated. Click on the "More" drop down toward the top of the forum page and select "Tags". An illustration of the tags used in posts shows up. You can click on a Tag you are interested in to generate a list of all related posts.
If you have not already, sign-up to the Renesas Rulz community, using the Join or Sign-in button at the top right of the page. Once you are signed-in you can post questions and replies. Ask a question you have about debugging techniques and see what kind of response you get. HoL
3.3.D: One of the more vexing types of bugs to track-down are those related to the operation of the program stack. If stacks are not sized correctly or used carefully errors can pop up that can seem completely unrelated to stack use. This application note, Mastering Stack Usage, provides an overview of and several specific techniques that can be used to monitor and analyze stack use during runtime. It illustrates these techniques using the IAR Embedded Workbench for Renesas Synergy (IAR EW for RS) and shows how to adjust stack size within the Synergy Configurator. Read and understand the key topics described in the application note. If you have IAR EW for RS installed follow along with the application note in the tool and see how the functions are used. AN
3.4 Intermediate debugging techniques for RTOS-based applications
Even though RTOS-based applications can be much less complex than monolithic implementations the introduction of an RTOS makes it possible to introduce RTOS-related bug. These lessons provide intermediate level debugging techniques useful in RTOS-based applications.
3.4.A: Read and understand the following Professor IoT article that discusses debugging RTOS-based applications. Follow that up by reading the article from Percepio, a Synergy partner, on RTOS trends and challenges. It includes a description of an RTOS challenge the NASA Pathfinder mission was faced with and some key debugging techniques that can be used to overcome these types of issues.
RTOS Aware debugging (An introduction to debugging RTOS-based applications) PIoT
RTOS trends and challenges (Embedded.com article by Percepio, a Synergy Partner)
3.4.B: The SSP User's Manual, SSP UM, includes a description on RTOS aware debugging in Section 188.8.131.52 titled "Using the RTOS Resources View with a Synergy Project". This section describes how to invoke the view and what functions are available. Read and understand this section and consider bookmarking it since it serves as an excellent reference when you are looking for a reminder of these capabilities and how to use them.
3.4.C: Using the RTOS Resources View with the Renesas Synergy™ Tools ISDE (Topic list included below) Vid
Describes how to view information within e2 studio on: Threads, Message Queue, Semaphores, Mutexes, Event Flags, Memory Block Pool, Memory Byte Pool, Timer, and System clocks.
3.4.D: Using IAR™ EW for Renesas Synergy™ Development & Analysis Tools (Via Renesas Academy)
To take this online course, sign-up for the Renesas Academy here: https://academy.renesas.com/ Click on the Course Catalog pull down and select Renesas Synergy. Click on the Course and scroll down to the module titled "Using IAR™ EW for Renesas Synergy™ Development & Analysis Tools". This online course covers RTOS-aware debugging, Static Analysis and Runtime Analysis. HoL
3.5 Using TraceX for debugging
TraceX is a valuable debugging tool for ThreadX-based applications. It can display information on Threads, their resources and details on program execution that can be invlauable in debugging and optimization.
3.5.A: Using Express Logic's TraceX with Renesas Synergy Tools e2 studio ISDE (Topic list included below) Vid
- Enable the use of TraceX
- Structure and functions of TraceX
- Requirement for ThreadX source
- Example illustration showing data analysis capabilities
3.5.B: The SSP User's Manual SSP UM, includes an overview of TraceX. Review Section 184.108.40.206 on Using Express Logic TraceX with a Synergy Project. Download TraceX from the Synergy Gallery and install it as described in the SSP User's Manual. Try it out on the familiar Threaded Blinky project to make sure it is installed and initialized correctly. HoL
3.5.C: The application note- "Procedure for debugging ThreadX RTOS applications using TraceX" covers installing, running and using TraceX. Follow the steps in this document to quickly get started with TraceX.
3.5.D: The TraceX User's Manual: Software is the most detailed source of information on the details of using ThreadX. It provides an overview of the TraceX 'cockpit' as well as details on all functions and features. Review the entire guide so you are familiar with the main features and capabilities. Be sure to look over the following features that can save you hours of time debugging complex projects:
- Thread Status and Event Display
- Performance Analysis and Execution Profile
- Generating Trace Buffers
- FileX, NetX and USBX Trace Events
3.5.E: A series of example trace files with the extension trx are found in the TraceFiles subdirectory of the TraceX installation. These pre-built examples will help you get comfortable with using TraceX on the trace buffers generated by ThreadX running with your application. One example trace file always present is the file demo_threadx.trx. This example trace file shows the execution of the standard ThreadX demo, as described in Chapter 6 of the ThreadX User Guide. As a hands on exercise use the this example file to try out the Display Overview, Title Bar, Tool Bar and other overviews in Chapter 3 of the TraceX User's Manual. HoL
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 and other helpful support resources.
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.