When diving into the SSP Framework, developers might have noticed that quite a few modules have a property for a callback. Embedded software developers who are new to real-time operating systems and have mostly programmed at the bare-metal level may be scratching their heads and wondering what exactly the deal is with these callbacks. In this post we are going to dive into the details on how callbacks are used within the SSP framework and cover best practices that will be helpful to both the novice and the seasoned professional.
Nearly every embedded system has asynchronous events that need to be handled by the system. These events could be button presses or even data being received or transmitted on a UART peripheral. Asynchronous events will typically be handled using interrupts but the SSP drivers and framework already include the definitions for all the interrupt functions. If a developer tries to create another interrupt handler, there will be a duplicate definition and the application will fail to build. The SSP Framework is designed to be scalable and easily adaptable and the mechanism for being able to specify which function should be called when an asynchronous event occurs is the callback.
A callback is nothing more than a regular function that is defined within the developer’s application code but is registered with a framework through its properties. The function must follow a specific pattern that the SSP is expecting that applies to all callbacks. The pattern is that the callback function must return void and take a structure, <interface>_callback_arg_t, as the parameter. Using a structure in this way provides flexibility to the framework by allowing different interfaces to meet different requirements while still maintaining a consistent interface.
The structure must contain an event member which tells the callback why the function was called in the first place. For example, a flash peripheral might have executed the callback because an erase event was completed, a write event was completed or other possible reasons. The callback function that the developer writes needs to determine which event occurred and what needs to be done about. In order to handle the event, an event member needs to be passed inside the callback arguments structure. A simple example how the event member is used within the callback can be seen below:
In addition to the event member, the callback structure also needs to include a context. A context is a pointer to the peripheral instance that the interrupt is associated with. As the reader can imagine, there could be multiple UART modules that are all sharing the same callback function. In order for the callback to figure out which module interrupted and needs handling, the context is used to provide that information to the callback.
Reading between the lines, the reader at this point probably realizes that callback functions are called from within an interrupt handler. Since the callback is used within an interrupt, a developer should follow proper design methodologies for interrupt handlers when they write their callback functions. These include but are not limited to
Keeping callbacks short
Minimizing function calls from within the callback
Getting in and out as quickly as possible
Minimizing creating and destroying variables
Optimizing the callback for speed
Re-entrant
Finally, after a developer has completed their callback function, they need to register it with the module. Registering the callback is the easy part. Simply go into the Synergy Configurator and access the thread that contains the framework. Click on the framework and in the properties window find the callback property. Insert the callback function name and then regenerate the SSP. The application can now handle asynchronous events!
Now that the reader understands callbacks and how to add frameworks into the application, next time we will examine how to use the framework code that is automatically generated by the Synergy Configurator. In the mean-time,
Live long and profit!
Professor_IoT
Hot Tip of the Week
Looking for a comprehensive overview of the key features, benefits and capabilities of the Synergy Platform in a simple brochure format? Check out the Renesas Synergy Platform brochure. In just a few pages it gives you a complete overview of how the Synergy Platform allows you to completely rethink your approach to embedded design. It explains how you will be able to accelerate time to market, eliminate barriers to entry and lower cost of ownership- the imperatives in today’s fiercely competitive IoT market. Check out the details at the link below: https://www.renesas.com/en-us/docs/products/synergy/Synergy_brochure_Final.pdf