This article will provide a guided step-by-step series of Introductory 'lessons' you can use to begin with Development in SSP. This article expands on the topics covered in the Perquisites to better solidify the key concepts: Run the Blinky Project and How to Create a New Synergy Project.
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 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 lessons 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 previous experiences.
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 An Introduction to Development in SSP
This article covers some of the basics needed to begin development in SSP. 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 Introduction to Development in SSP Lessons
The below lessons provide a lesson-based guided step-by-step process for mastering the basics of development using 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 SSP and RTOS Development Basics
The following lessons provide a quick introduction to the use of an RTOS in embedded designs and the key concepts behind development with SSP. 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.A: Read and understand these Professor IoT posts describing key RTOS concepts used in ThreadX-based SSP projects.
Drivers, Frameworks and Threads, oh my! (Walks through drivers, frameworks and threads and how to best use them within the development environment) PIoT
Transitioning to ThreadX: Creating Threads (Explores RTOS concepts and demonstrates how they help developers decrease system complexity) PIoT
3.1.B: Read over these sections in the SSP User's Manual, SSP UM, to familiarize yourself with what and where information is available. This is a very large document that covers significant amount of detail, but you will only need to read over a small fraction of it. The majority of the document is for reference and you only need to understand where to find things you might want to reference during development.
- Quickly scan/read section 2.5.1 to capture the key concepts of the SSP Architecture including Modules, Interfaces, Layers and Callbacks. No need to memorize all this, but it will be useful to have it as background where you see the terms and concepts play out during development. You can always refer back to this section when you have questions.
- Quickly scan/read section 2.6 on the Board Support Package (BSP) Architecture. Make sure you understand what elements are included in the BSP and in what order key elements are executed during start-up. These will be helpful when you work with the resources on your target board. Remember what is covered so you can come back to this section if you need to.
- Chapter 3 includes a user guide for e2 studio and an overview of IAR Embedded Workbench for Renesas Synergy, your two Integrated Synergy Development Environments (ISDE) options. Read over the sections covering option you will be using. You should already have installed your ISDE and gotten Blinky working so focus on skimming/reading over the sections on using the ISDE to create projects, add threads, configure modules, building and debugging a project. You need to read everything, just get a good idea of the development flow and remember where this information is if you need to look it up later.
3.1.C: Express Logic provides some excellent documentation to help you come up to speed on and to dig into the details of RTOS-based development. Check out these resources to fill in any gaps on your RTOS knowledge.
- What is an RTOS (An overview of what an RTOS is and how to use it) AN
- ThreadX User Manual (Part of the complete X-Ware Component Documents for Renesas Synergy zip file, at the bottom of the page- covers ThreadX basics and deep details) AN
- Real Time Embedded Multithreading using ThreadX (The authoritative book by Edward Lamie on ThreadX with lots of details, examples and exercises) HoL
3.2. Key Synchronization Concepts used in ThreadX and SSP
Use the following exercises to learn how to use synchronization constructs to communicate between threads in a ThreadX RTOS project in SSP. This is one of the most common and useful techniques for simplifying communication between threads in multi-thread projects.
3.2.A: Read and understand the following Professor IoT posts. They illustrate synchronization concepts and the constructs used in ThreadX.
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) PIoT
Transitioning to ThreadX: Semaphores (What semaphores are and how and why to use them) PIoT
3.2.B: After you have done the above exercise, try a hands-on exercise to see this technique at work. Run Threaded Blinky on your kit. Modify the project by adding another thread that uses a Semaphore to signal the LED. You can find the source code for Threaded Blinky here if you need a starting point.
Transitioning to ThreadX: Mutexes (What mutexes are and how and why to use them) PIoT
Transitioning to ThreadX: Event Flags (What event flags are and how and why to use them) PIoT
3.2.C: After you have done the above exercise, try a hands-on exercise to see this technique at work. What to do. Where to find: https://www.renesas.com/software/D6001595.html HoL
3.3 Advanced ThreadX Concepts
Use the following exercises to learn how to use advanced ThreddX capabilities to avoid RTOS limitations and issues.
3.3.A: Read and understand the following Professor IoT posts. They illustrate the key issues around thread priority and how to properly assign and manage thread priority.
Transitioning to ThreadX: Managing Thread Priorities (Explores prioritizing threads through rate monotonic analysis/scheduling) PIoT
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) PIoT
Transitioning to ThreadX®: Avoiding Deadlock (aka The Deadly Embrace, how Deadlock occurs, why it’s bad, how to avoid it) PIoT
3.3.B: If you are interested in learning more about priority inversion and how ThreadX helps mitigate this with the advanced Preemptive Threshold capability you can read over this Express Logic article. https://rtos.com/wp-content/uploads/2017/10/EL_PTS_Improves_Performance.pdf. It describes in detail the key issues and how the Preemptive Threshold feature address them.
3.3.C: Read and understand the following Professor IoT posts. They illustrate some additional advanced topics that can impact more complex types of designs with multiple threads and tight real-time response requirements.
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) PIoT
Transitioning to ThreadX®: Thread Starvation (Symptoms of thread starvation, how to identify where it’s coming from and how to get rid of it) PIoT
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) PIoT
3.3.D: As a hands-on exercise, edit the Threaded Blinky project to add two additional threads that determine the on and off times of the LED. Use a semaphore to share the LED resource between these two threads. Can you get the LED to stay stuck on or stuck off if the thread priorities are set incorrectly? What happens if you also share a timer between these two threads? Could one thread be starved for the LED resource while the other is starved for the Timer? You can find the source code for Threaded Blinky here if you need a starting point. HoL
3.4 Connecting Threads
Use the following exercises to learn about advanced development techniques useful for connecting various threads in ThreadX-based development projects in SSP.
3.4.A: Read and understand the following Professor IoT articles describing optimization techniques.
Transitioning to ThreadX®: Memory Pools (What memory pools are and how and why to use them) PIoT
Transitioning to ThreadX: Message Queues (What message queues are and how and why to use them) PIoT
Getting started with the Messaging Framework (Explores the Messaging Framework capabilities and examines how to subscribe to an Application Framework Components messages.) PIoT
3.4.B: The Messaging Framework module guide has a good example of using messages in a simple project. Download the project, read the associated application note and run the associated Application Project. Make sure you understand how messages are created and used in SSP. They can be a critical component in connecting multiple threads. https://www.renesas.com/search/keyword-search.html#q=R11AN0096 HoL
3.4.C: The GUIX Hello World application note has a good example of using messages in a simple project. Download the project, read the associated application note and run the associated Application Project. Make sure you understand how the messages are used to communicate between threads. Consider extending the application project by adding a simple thread that just counts timer ticks. Can you communicate this value to another thread so it can be displayed periodically as part of the Hello World notification? https://www.renesas.com/en-us/search/keyword-search.html#q=R12AN0021 HoL
3.5 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.5.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.5.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
3.5.C: As a hands-on exercise select a Module Guide for a Framework module you are interested in. Import the project, and review the code. Run the project and analyze the worst case memory usage and stack size. Can you save some memory by making changes to the configuration settings as described in the previous exercises? How do the memory sizes compare with those in the SSP Datasheet? You can find Module Guides and the associated Application Projects on this page https://www.renesas.com/products/synergy/tools-kits.html#sampleCodes HoL
3.6 Additional Topics
Use the following exercises to learn about some additional RTOS related capabilities specific to SSP.
3.6.A: Read and understand the following Professor IoT articles describing additional topics.
Transitioning to ThreadX®: Customizing ThreadX (Adding ThreadX to a project, optimizing ThreadX performance, configurable properties) PIoT
Blocking versus Non-Blocking Renesas Synergy™ Software Components (Non-blocking HAL drivers have Callbacks associated with them, Frameworks block by default) PIoT
3.6.B: As a hands-on exercise select a Module Guide for a Framework module you are interested in. Import the project, and review the code. Run the project and analyze the worst case memory usage and stack size. Can you save some memory by making changes to the configuration settings as described in the previous exercises? How do the memory sizes compare with those in the SSP Datasheet? You can find Module Guides and the associated Application Projects on this page https://www.renesas.com/products/synergy/tools-kits.html#sampleCodes HoL
4.0 What's Next?
Use these lessons to learn more about RTOS-based projects using Synergy Platform-based designs.
Debugging RTOS-based Projects: Once you are familiar with RTOS concepts and the ThreadX implementation in SSP you will probably start creating your own projects. These projects might have bugs in them. If they do, we suggest you read the article on Advanced Debugging topics, with several lessons on debugging ThreadX implementations in SSP. Additional debugging exercises cover debugging techniques for power, performance and memory footprint optimization- which might also be useful.
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.
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.