Skip to main content
Knowledgebase
Home
Renesas Singapore - Knowledgebase

Getting Started with RTOS-based projects with the Synergy Software Package

Last Updated:01/04/2018

Question:

How do I get started with RTOS-based projects in SSP?

Answer:

This article will provide a guided step-by-step series of 'lessons' you can use to get started with RTOS-based projects in SSP.

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 additional resources to help all your Synergy Platform development efforts.

2   RTOS-based Projects in SSP

This article covers some of the basics needed to begin development in SSP of projects use the wealth of capabilities available for RTOS-based designs. The use of an RTOS is a significant productivity enhancer when complex projects, that use a GUI, Networking, USB communications, file systems and other advanced capabilities are a requirement. This article will describe the key elements used when implementing projects using an RTOS and will help cement these concepts with a variety of hands-on exercises. Typically these exercises are short and to the point so you can learn quickly, without needing to wade through a mountain of User Manuals and Data Sheets.

Review the below list to see if the topics you are interested in are covered in this article.

  • An introduction to RTOS-based embedded systems
  • Using threads in an ThreadX project
  • Key ThreadX constructs
    • Thread Priority
    • Managing stack size
    • Task Synchronization (Semaphores, Mutexes, and Event flags)
  • Advanced ThreadX concepts
    • Priority inversion, Starvation, Jitter, and Event chaining)
    • Optimization for speed

 

3    Using the ThreadX RTOS in SSP Lessons

The below lessons provide a lesson-based guided step-by-step process for mastering the basics of using ThreadX with SSP. 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)

Note: Some of the exercises in 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    An Introduction to RTOS-based Embedded Development in SSP

The following lessons provide a quick introduction to the use of an RTOS in embedded designs. Even if you feel you are familiar with this material, it is helpful to at least scan over it to make sure you are familiar with the terms and environment used as this will avoid confusion later on.

3.1.1    RTOS-Bbased Embedded Development

Use the following exercises to become familiar with the key concepts behind RTOS-based embedded development.

3.2.1.A:    Read and understand these Professor IoT posts introducing key RTOS concepts used in 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

Transitioning to ThreadX – Optimizing RTOS Applications for Speed (Maximizing ThreadX applications for performance, i.e. processing speed and power)

Using Renesas Synergy Software SSP Module Guides – Part 2 (Importing the application project, Chapters 7-9)

The Renesas Flash Programmer: Programming and Configuration (Loading code through the Flash programmer)

The Renesas Flash Programmer: Setting up the hardware and software (Renesas Flash programmer vs. stand-alone Flash programmer, RFP better for small production batches. How to use RFP.)

Using Renesas Synergy Software SSP Module Guides – Part 1 (How to use MGs, specifically Chapters 1-6)

Getting Familiar with the new Linker Editor (How to use the linker file configurator)

Improving Software Quality using the C-Stat Static Code Analysis Tool (How to get started with and use C-Stat, a commercial static code analyzer available in the IAR Embedded Workbench)

RAM Optimization Techniques for Renesas Synergy™ Applications (Optimizing the BSP, process stack, main stack. Performing a worst-case stack analysis on each thread. Use the compiler to optimize code.)

Measuring the Renesas Synergy™ Software SSP’s Software Quality (Five key indicators of software quality: Code base vs. coding standards, complexity of software functions, establishing traceable requirements, zero errors and zero warnings, achieving full test coverage.)

Transitioning to ThreadX® – Optimizing RTOS Applications for Memory Usage (Memory optimization via worst-case stack analysis, minimizing number of threads/ThreadX objects in an application, using memory block pools when dynamically allocating memory, using the compiler)

Blocking versus Non-Blocking Renesas Synergy™ Software Components (Non-blocking HAL drivers have Callbacks associated with them, Frameworks block by default)

Transitioning to ThreadX®: Event Chaining (Good for simplifying software with multiple suspension objects, reducing the total number of threads/objects in an app, using notifications to allow a thread to wait on multiple resources)

Transitioning to ThreadX®: Getting over the Jitters (Reasons for thread jitter occurrence, ways to discover thread jitters and suss them out, ways to get rid of thread jitters)

Transitioning to ThreadX®: Thread Starvation (Symptoms of thread starvation, how to identify where it’s coming from and how to get rid of it)

Transitioning to ThreadX®: Avoiding Deadlock (aka The Deadly Embrace, how Deadlock occurs, why it’s bad, how to avoid it)

Transitioning to ThreadX: Avoiding Priority Inversion Issues (High priority thread preempted by a lower priority thread, how it happens and how to stop it from happening)

Transitioning to ThreadX®: Customizing ThreadX (Adding ThreadX to a project, optimizing ThreadX performance, configurable properties)

Transitioning to ThreadX®: Memory Pools (What memory pools are and how and why to use them)

Transitioning to ThreadX: Message Queues (What message queues are and how and why to use them)

Transitioning to ThreadX: Event Flags (What event flags are and how and why to use them)

Transitioning to ThreadX: Mutexes (What mutexes are and how and why to use them)

Transitioning to ThreadX: Semaphores (What semaphores are and how and why to use them)

Transitioning to ThreadX: Task Synchronization (examines synchronization objects available in ThreadX and when each should be used, i.e. mutexes, semaphores, event flags, message queues)

Introduction to the Synergy Wi-Fi Framework (Renesas Wi-Fi framework removes complications typically associated with incorporating wireless connectivity into embedded systems)

Transitioning to ThreadX: Getting up to speed with TraceX (examines TraceX and how developers can use it to see which threads are executing and when)

Transitioning to ThreadX: Managing Thread Priorities (explores prioritizing threads through rate monotonic analysis/scheduling)

Transitioning to ThreadX: How to Size the Stack for a Thread (how to make sure a thread is properly sized using a Thread Control Block)

Transitioning to ThreadX: Creating Threads (explores RTOS concepts and demonstrates how they help developers decrease system complexity)

Switching from e2 Studio to IAR Embedded Workbench® for Renesas Synergy (how to convert an e2 studio project to an IAR Workbench project in just a few minutes)

Synergy Platform Resources Every Developer needs to Know (the basics of what developers need to know to work with SSP)

Importing and Exporting Synergy Software Projects (how to import and export projects with SSP)

Updating Application Software using a Flashloader (how to perform software updates using the Synergy Software Flashloader Framework)

Using Synergy Software Generated Framework Code in Applications (how to use the automatically generated code along with tips and tricks for looking up the API and accessing the documentation)

Understanding SSP Framework Callbacks (dives into the details on how callbacks are used within the SSP framework and cover best practices that will be helpful to developers)

Adding Frameworks and Modules to the Synergy Software BSP (how to add frameworks and modules to a board support package along with important considerations that developers need to take into account when configuring frameworks)

Configuring the Board Support Package (BSP) using the Synergy Configuration Tool (how to configure and customize the BSP)

Creating a Custom Board Support Package (BSP) (how and why to create a custom BSP)

An Introduction to the SPI Application Framework (how a developer can get the SPI application framework up and running)

Communicating on the IIC bus is now easier than ever (advantages of having a built-in IIC framework in the Synergy platform)

Jump-start Analog Measurements using the ADC Periodic Application Framework (the ADC periodic application framework dramatically simplifies interfacing with the analog world)

Saving the Day with the Thread Monitor Framework (thread monitor framework acts as a watchdog looking for potential problems in thread execution)

Simplifying Interrupts with the External IRQ Framework (makes configuring external interrupts simple)

The Synergy Platform’s very own Console Framework (how and why a developer can get a console up and running over UART)

“Hello World” using the UART Application Framework (explores the Renesas Synergy UART Application Framework and walks through the necessary steps to get it up and running on a SK-S7G2 starter kit and say “Hello World!”)

Getting started with the Messaging Framework (explores the Messaging Framework capabilities and examines how to subscribe to an Application Framework Components messages.)

Drivers, Frameworks and Threads, oh my! (walks through drivers, frameworks and threads and how to best use them within the development 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
    • Waveform

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    Using ThreadX in SSP

Use the following exercises to become familiar with key concepts needed to efficiently use ThreadX in SSP.

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. Open 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   Optimizing ThreadX Projects in SSP

Use the following exercises to learn about advanced development techniques useful for optimizing ThreadX-based development projects in SSP.

3.2.4.A:    Read and understand the following Professor IoT articles describing optimization techniques.

Transitioning to ThreadX® – Optimizing RTOS Applications for Memory Usage (Memory optimization via worst-case stack analysis, minimizing number of threads/ThreadX objects in an application, using memory block pools when dynamically allocating memory, using the compiler) PIoT

Transitioning to ThreadX – Optimizing RTOS Applications for Speed (Maximizing ThreadX applications for performance, i.e. processing speed and power) PIoT

Transitioning to ThreadX: How to Size the Stack for a Thread (How to make sure a thread is properly sized using a Thread Control Block) PIoT

RAM Optimization Techniques for Renesas Synergy™ Applications (Get the most out of your MCU RAM) PIoT

 

3.2.4.B:    The SSP Data Sheet has estimates for memory usage for SSP modules. These estimates can be helpful when optimizing SSP projects for code and memory footprints. Read over the SSP Datasheet to become familiar with these estimates and how they can be useful when optimizing your project. The most recent version of the SSP Datasheet is available on the Synergy Gallery in the Release Archive tab for SSP. https://synergygallery.renesas.com/ssp/archive#read 

 

 

4.0    What's Next?

Use these lessons to learn more about RTOS-based projects using 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

RTOS-based development 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.

 

6.0    Prerequisites 

Before you begin development 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.

Suitable Products
SSP