Writing and Testing Your First RTOS Project with MQX Class 2: Defining the Tasks and Elements April 22, 2014 Charles J. Lord, PE President, Consultant, Trainer Blue Ridge Advanced Design and Automation

This Week’s Agenda 4/21 Getting Started and Some Basics 4/22 Defining the Tasks and Elements 4/23 Writing Our First Task 4/24 Completing Our Code 4/25 Debugging our RTOS Application

This Week’s Agenda 4/21 Getting Started and Some Basics 4/22 Defining the Tasks and Elements 4/23 Writing Our First Task 4/24 Completing Our Code 4/25 Debugging our RTOS Application

In this class we will block out our code and define what tasks will need to be written and how they will need to interact. We will look at the elements or modules that we will need to make use of in the RTOS.

Our Target

Adding an Accelerometer The KWIKSTIK board does not have an on-board accelerometer – however it does have the “TWRPI” interface, into which we can plug the TWRPI-MMA845XQ triaxial accelerometer.

KWIKSTIK Front TP 1 TP 2 TP 3 TP 4 TP 5 TP 6

KWIKSTIK Back USB Debug

Design Specifications Touch “button” 1 to initialize Display reads “READY” Touch “button” 2 to start Display reads “GO” Unit reads accelerometer for 15 seconds Will integrate max G-force over that time Readout will give a relative reading of total G-force

Possible additions? Set test time to a custom or choice of other times Calibrate workout readout (based on weights used?) Output via USB, etc to other devices or PC Others?

Tasks Read Accelerometer and accumulate (integrate) Timer OR: simulate this with random number generator Timer Read buttons (input handler) Display driver Initialize / Idle

Events Button press (touch pad touched)

MQX RTOS Tasks A system consists of multiple tasks Tasks take turns running Only one task is active (has the processor) at any given time MQX manages how the tasks share the processor context switching Task Context Task Stack - Data structure stored for each task. State of processor registers / owned resources are stored when task is pre-empted and then restored when task resumes. To start things off, lets think about how we solve problems as engineers. You have a big problem to solve. In order to make it more manageable, you then break it down into little problems to tackle individually. It is the same idea when using an RTOS. You have a software problem you’re trying to solve, and so you break it down into chunks, which are called tasks. An RTOS system consists of one or more tasks that work together to solve a larger problem. The tasks takes turns running, as only one task, called the active task, has the processor at any one time. The RTOS then uses what is called a scheduler to determine how those tasks share the processor. And when a new task takes control of the processor, that’s called a context switch. By performing many context switches quickly, you can create the illusion of concurrency. However only task is active at a time.

Typical Task Coding Structure A task may be instantiated more than once.

Task States A task is in one of these logical states: blocked active Task is blocked and therefore not ready It is waiting for a condition to be true active Task is ready and running because it’s the highest-priority ready task Ready Task is ready, but not running because it’s not highest-priority ready task terminated the task has finished all its work, or was explicitly destroyed

Context Switching If Task A running, it will stop, call the scheduler if: Calls a blocking function (e.g _time_delay(x)) A higher priority task is made ready Interrupt Occurs Then: Context of Task A is stored Context of highest priority task in ready queue is restored Task A gets put in ready queue The highest priority task may be the same task, so may still keep running depending on why the task originally stopped 16

Task States Active Blocked Terminated Ready Task Finishes Explicit Termination Blocking Call Higher-priority Task becomes Ready Time Slice Expires Interrupt comes in Terminated Blocked Context Switch This diagram shows the visual representation of the different task states. Looking at the active task, it can go to the terminated state if the task finishes its work or becomes explicitly terminated. If it calls a blocking call, then it goes into the blocked state. This means it is now waiting for some condition to become true. Finally if a higher priority task becomes ready, its time slice expires, or an interrupt occurs, then the active tasks gets put into ready state. At that point a context switch occurs, and a task that was in the ready queue gets promoted to being the active task. If a task becomes unblocked because that condition became true, then it gets put into the ready state and the schedule determines if it is the highest priority task that could be running, and does a context switch if that is the case. Also when a task is first created, it gets put into the ready state. Object Available Timeout Expires Task Starts Ready 17

Events Events can be used to synchronize a task with another task or with an ISR. If the event that a task is waiting on is not set, the task is put into the wait queue (blocked). When the event that a task is waiting on is set, the MQX scheduler puts the task into the ready queue. With auto-clear, no need to clear bits manually 18

Event Groups Tasks can wait for a combination of event bits to become set. Tasks can set or clear a combination of event bits. Tasks can wait for any or all specific event bits in an event group (with an optional timeout) Task or ISR code _lwevent_set AND OR Tasks or ISR’s can set event bits If only identified by index, then a fast event group, since don’t have to wait for name translation From the MQX User’s Guide (MQXUG) Lightweight Events Lightweight events are a simpler, low-overhead implementation of events. The lightweight event component consists of lightweight event groups, which are groupings of event bits. The number of event bits in a lightweight event group is the number of bits in _mqx_uint. Any task can wait for event bits in a lightweight event group. If the event bits are not set, the task blocks. Any other task or ISR can set the event bits. When the event bits are set, MQX puts all waiting tasks, whose waiting condition is met, into the task’s ready queue. If the lightweight event group has autoclearing event bits, MQX clears the event bits as soon as they are set and makes one task ready. _lwevent_create 32 bits TaskA TaskB _lwevent_wait_for (any) _lwevent_clear _lwevent_wait_for (all) _lwevent_clear 19

Creating an Event Include lwevent.h #include <lwevent.h> Declare event group and bit mask Create the event #include <lwevent.h> LWEVENT_STRUCT Event; #define HVAC_STATUS_CHANGED 2 _lwevent_create(Event, 0); _lwevent_create() is called with a pointer to the variable and a flag indicating, whether the event group has autoclearing event bits. (0 indicates event bits not auto-clearing)

Using an Event Set the event _lwevent_set(Event, HVAC_STATUS_CHANGED); In another task, wait for the event to set Clear the event _lwevent_set(Event, HVAC_STATUS_CHANGED); _lwevent_wait_for(Event, HVAC_STATUS_CHANGED,1,0); _lwevent_clear(Event, HVAC_STATUS_CHANGED); _lwevent_wait_for(Event, HVAC_STATUS_CHANGED,1,0); Description of _lwevent_wait_for(): Waits for all or any of the specified event bits in a lightweight event group for a specified tick-time period. Parameters explained: 1st parameter = Event variable (pointer) 2nd parameter = Event bit combination (mask) 3rd parameter = 1 , Wait for all bits of bit mask set (wait for exact bit combination to occur) 4th parameter = 0, No timeout

Using an Event Task B Task A Wait for the event, then clear it Set the event Void TaskA_Task(void) { _lwevent_set(…); } Void TaskB_Task(void) { _lwevent_wait_for(…); _lwevent_clear(…); } _lwevent_wait_for(Event, HVAC_STATUS_CHANGED,1,0); Description of _lwevent_wait_for(): Waits for all or any of the specified event bits in a lightweight event group for a specified tick-time period. Parameters explained: 1st parameter = Event variable (pointer) 2nd parameter = Event bit combination (mask) 3rd parameter = 1 , Wait for all bits of bit mask set (wait for exact bit combination to occur) 4th parameter = 0, No timeout

A Better View of MQX Structure

MQX Board Support Package What is a Board Support Package (BSP)? Startup code for the processor Initialize memory, clock, interrupt controller All the drivers needed with the proper settings Application Stacks (TCP/IP,USB,etc) RTOS BSP

Tomorrow We will bring up CodeWarrior 10.6 and MQX 4.1 and begin coding! Software (30-day evaluation) available from freescale.com Takes a LONG while to download – only download Kinetis support unless you will need other processors (S08, Coldfire, etc)

This Week’s Agenda 4/21 Getting Started and Some Basics 4/22 Defining the Tasks and Elements 4/23 Writing Our First Task 4/24 Completing Our Code 4/25 Debugging our RTOS Application

Please stick around as I answer your questions! Please give me a moment to scroll back through the chat window to find your questions I will stay on chat as long as it takes to answer! I am available to answer simple questions or to consult (or offer in-house training for your company) c.j.lord@ieee.org http://www.blueridgetechnc.com