If you are new to Processor Expert in MCU10, and new to FreeRTOS, then you need to learn two new things in parallel the same time. That might be overwhelming. But don’t worry: if you do things step by step and slowly the first time, this much easier than you might think. This tutorial shall help you with this.

This is a step-by-step tutorial about how to create a project with CodeWarrior for MCU10.2, Processor Expert and the DEMOJM board. The goal is to create a project from scratch with two tasks blinking an LED. This tutorial uses the DEMOJM board, but in practice any other ColdFire/Kinetis/S08 board can be used as well.

The Board

I’m using the Freescale DEMOJM board with the S08 MC9S08JM16 CPU. This board allows swapping microcontrollers (S08JM16, S08JM60 and ColdFire V1 MCF51JM128). The board has useful components (LEDs, buttons, accelerometer, butter) and the pins of the microcontroller routed to a connector, making it a  good board to connect with my own hardware.

I’m using here the MC9S08JM16 controller with 16 KByte of FLASH and 1 KByte of RAM. Sounds tiny for running it with an RTOS, but not a problem for FreeRTOS :-). The JM16 CPU has a built-in USB feature, but this is another topic with Processor Expert.

Needed Software/Tools (if not already installed)

To get things started, CodeWarrior plus additional Processor Expert components need to be installed:

1. CodeWarrior for MCU10: http://www.freescale.com/cwmcu10
2. FreeRTOS.PEupd Processor Expert component: http://www.steinerberg.com/EmbeddedComponents/FreeRTOS
3. LED.PEupd Processor Expert component: http://www.steinerberg.com/EmbeddedComponents/LED
4. Utility.PEupd Processor Expert component: http://www.steinerberg.com/EmbeddedComponents/Utility

Install CodeWarrior. Then install the downloaded *.PEupd Processor Expert components using the menu Processor Expert > Import Package:

In the next dialog, select the package(s) to import:

Hint: You can select and import multiple packages in one step

Creating the project with the wizard

In CodeWarrior, I select the menu File > New > Bareboard Project and provide a project name:

Pressing ‘Next’. This gives me the device selection dialog:

Hint: using wildcards like *jm16 helps me to select quickly the device.

Pressing Next. This gives me the list of connection methods:

I keep the P&E USB Multilink, as this is the debug interface on board of my board.

Pressing ‘Next’. This gives a choice of programming languages:

I stick with the default (C) and press ‘Next’. This gives me the opportunity to use Processor Expert:

Pressing ‘Next’. Now I can select the pin variant of my processor:

I select the QFN package on the board. Now I can press ‘Finish’, and my project gets created and shows up in the CodeWarrior Projects View:

Showing Processor Expert Views

If this is my first Processor Expert project in the workspace, then the Processor Expert views are not loaded yet. To open the views with one click, the menu Processor Expert > Show Views is used:

This opens a set of additional Processor Expert views:

• Project Panel View: shows the ProcessorExpert.pe which contains all the components.
• Components Library View: Lists all registered components.
• Component Inspector View: For editing the currently selected component.

Adding LEDs

Usually I need to look at the schematics of a board to see to which microcontroller pins the LED’s are connected. The nice thing with the DEMOJM board is that this is clearly labeled: PTE2 and PTE3 are used for the first two LED.

I’m going to add two LED components to my project. For this I drag&drop two LED components from the Components Library view to my Project Panel view:

I do this twice to have two LED in my project: LED1 and LED2.

To connect the LED to the microcontroller pin:

1. Select the LED component
2. In the Component Inspector, use the LED Pin drop down. You need to click into the field to see the drop down triangle:
   

   Interface drop down before click

   Once clicked, there is a drop-down visible:

   

   Clicked with drop down visible

3. and select LEDpin (BitIO) as interface

Note: for ARM/Kinetis, the LDD (Logical Device Driver) HW Interface is used. This is not explained here, as very different. Guess I need to write another tutorial for Kinetis 😉

With this interface added, the interface needs to have some additional information (properties marked in red color):

I need to select PTE2 as pin for my first LED:

Doing the same thing to assign PTE3 to LED2:

Adding FreeRTOS

I could add the same way the FreeRTOS to the project. Or I select the component and use the ‘+’ icon:

Doing this will show the following dialog:

The FreeRTOS component is using a shared Utility component, and as we do not have added it yet, it asks to create a new one. Clicking OK will add both the FreeRTOS and the Utility:

RTOS Software Interrupt Vector

Again, the FreeRTOS component needs some additional settings. Unfolding the component shows that the software interrupt vector needs to be configured:

The operating system needs an interrupt vector for so called ‘system calls’: the way how the RTOS can raise an interrupt to initiate a context switch or similar things. This is typically done with a software interrupt instruction or a trap instruction. For the S08 core this is done with the SWI (Software Interrupt) assembly instruction.

I need to configure the vector to use the one used for the software interrupt instruction, which is the ‘swi’ vector on the S08 core:

The other thing the RTOS needs is the tick counter: If needed, I can change here the timer device and the period (which is by default 10 ms):

RTOS Tick Counter/Timer

In case I change the timer tick rate, I need to tell the RTOS the changed Tick Rate Frequency:

I have not found an elegant way in the component to automatically change the RTOS Tick Rate (Hz) based on the timer frequency. So it is not ideal to have the setting in two places, but this is how it works right now.

For the S08 core the SWI interrupt settings are simple: there is only one vector possible.

If I would use the ColdFire MCF51JM128 with my board, then the Processor Expert FreeRTOS component would recognize the V1 core being used, and enable the ColdFire V1 settings. As the interrupt settings differ from family to family, and multiple vectors are possible, I have a choice of different vectors:

In the RTOS component I need to specify the CPU family and the interrupt vector used:

Time to go back to the S08JM16 now…

CPU Stack Size

We are using a tiny S08JM16 with only 1 KByte of RAM. Processor Expert is generating as well the linker file which has an allocation for the stack. By default this is 0x80 (128 bytes) for the S08JM16. But as we are using a separate stack for each RTOS task, I need less. I reduce the stack size needed for this in the Processor Expert settings. The settings are in the CPU component, Build Options tab:

I have set to 0x50 in this project. This has to be enough for:

1. Startup code (__startup(), initializing memory after reset).
2. Calling main().
3. Everything I do in main(), including interrupts. Note that I will create tasks in main() and start the scheduler.

Hint: how to know how much stack is needed? I use a very simple method: I allocate initially enough stack, then while debugging I write a pattern (e.g. 0xFF) into the stack area using the Memory View. Then I execute my code and immediately see what is changed in memory. This plus a margin of say 10% is then my number.

Task Default Stack Size

The other thing to think about is how much stack size I want to use by default for each task. This is configured in the RTOS properties:

I have it changed here to 100 as this should be enough for my tiny application.

Note: the ‘minimal stack size’ is using ‘stack units’ as entity. For the S08 core this is a byte, so ‘100’ means ‘100 bytes’. But for other architectures (e.g. ColdFire or Kintetis/ARM) a stack entry is 4 bytes, so then ‘100’ means really ‘400 bytes’.

The generated code will use that value for the macro configMINIMAL_STACK_SIZE which I can use in my code. That minimal stack size is used for the FreeRTOS IDLE Task, so should be chosen carefully. But it is possible at run-time to spend more stack for the user tasks at task creation time.

Note: Keep in mind that for architectures *not* having a separate stack for the interrupts (like the S08), the stack size should be large enough as well for the interrupts happening at the task execution time. Many weird problems are caused by stack overflows. FreeRTOS has ways to detect stack overflows, but in any doubt it is a good practice to increase the stack size in case of problems to see if this solves a problem.

FreeRTOS Heap Size

FreeRTOS is using a dynamic heap for task stacks and descriptors. That heap is used as well for other RTOS infrastructure like queues and semaphores. As my microcontroller used only has 1 KByte of RAM, I set it to 800 bytes (which leaves 200 bytes for other global variables and system stack):

Saving Processor Expert Settings

Unsaved Processor Expert settings are indicated with a ‘*’ in the Component Inspector. To save the settings, I press CTRL-S (for Save) or use the Save All toolbar icon:

Generating Code

Now it is time to generate code with our components. An easy way to generate code is

1. Select the .pe file
2. Press the ‘generate code’ toolbar icon in the Project Panel View

Progress of code generation is reported with progress information:

Additionally status information is shown in the Console View:

Inspecting Generated Code and Documentation

The generated code and documentation is placed into two special folders inside the project:

It has generated as well a file ProcessorExpert.c which contains the main() (see Disable my Code Generation for more details):

Adding Two Tasks

Tasks in FreeRTOS are easy to implement. Below is the source code for two tasks which blink one LED each. To delay the task for a specific time the RTOS API function vTaskDelay() is used:

static portTASK_FUNCTION(Task1, pvParameters) {
(void)pvParameters; /* ignore unused parameter */
for(;;) {
LED1_Neg(); /* toggle LED */
FRTOS1_vTaskDelay(100/portTICK_RATE_MS); /* wait for 100 ms */
} /* for */
}

static portTASK_FUNCTION(Task2, pvParameters) {
(void)pvParameters; /* ignore unused parameter */
for(;;) {
LED2_Neg(); /* toggle LED */
FRTOS1_vTaskDelay(500/portTICK_RATE_MS); /* wait for 500 ms */
} /* for */
}

An easy place for this is to add the above code just above main().

Note: FRTOS1_vTaskDelay() is a simple wrapper (a define) to the vTaskDelay() function. You can use both versions as they are the same.

If I want to know more about an RTOS API function, I hover the mouse over the method:

Tip: I can drag&drop the method from the Project Panel view into the source file: that saves me a lot of typing.

Inside main() I need to create the two tasks, plus starting the scheduler:

(void)FRTOS1_xTaskCreate(Task1, (signed portCHAR *)"Task1", configMINIMAL_STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL);
(void)FRTOS1_xTaskCreate(Task2, (signed portCHAR *)"Task2", configMINIMAL_STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL);
FRTOS1_vTaskStartScheduler();

This creates two tasks (Task1 and Task2) using xTaskCreate() with following arguments:

• Task function name (Task1)
• Task name for debugging (“Task1”)
• Task stack size: configMINIMAL_STACK_SIZE
• Task startup argument: NULL for none
• Task initial priority (tskIDLE_PRIORITY)
• Pointer to task handle (NULL for none)

With vTaskStartScheduler() the RTOS scheduler will create an additional internal IDLE task and then run the RTOS.

Here is now how the code looks like for the whole source file:

/** ###################################################################
**     Filename    : ProcessorExpert.c
**     Project     : ProcessorExpert
**     Processor   : MC9S08JM16CGT
**     Version     : Driver 01.12
**     Compiler    : CodeWarrior HCS08 C Compiler
**     Date/Time   : 2012-06-27, 18:19, # CodeGen: 0
**     Abstract    :
**         Main module.
**         This module contains user's application code.
**     Settings    :
**     Contents    :
**         No public methods
**
** ###################################################################*/
/* MODULE ProcessorExpert */

/* Including needed modules to compile this module/procedure */
#include "Cpu.h"
#include "Events.h"
#include "LED1.h"
#include "LEDpin1.h"
#include "LED2.h"
#include "LEDpin2.h"
#include "FRTOS1.h"
#include "RTOSSWI1.h"
#include "TickCntr1.h"
#include "UTIL1.h"
/* Include shared modules, which are used for whole project */
#include "PE_Types.h"
#include "PE_Error.h"
#include "PE_Const.h"
#include "IO_Map.h"

/* User includes (#include below this line is not maintained by Processor Expert) */
static portTASK_FUNCTION(Task1, pvParameters) {
(void)pvParameters; /* ignore unused parameter */
for(;;) {
LED1_Neg(); /* toggle LED */
FRTOS1_vTaskDelay(100/portTICK_RATE_MS); /* wait for 100 ms */
} /* for */
}

static portTASK_FUNCTION(Task2, pvParameters) {
(void)pvParameters; /* ignore unused parameter */
for(;;) {
LED2_Neg(); /* toggle LED */
FRTOS1_vTaskDelay(500/portTICK_RATE_MS); /* wait for 500 ms */
} /* for */
}

void main(void)
{
/* Write your local variable definition here */

/*** Processor Expert internal initialization. DON'T REMOVE THIS CODE!!! ***/
PE_low_level_init();
/*** End of Processor Expert internal initialization.                    ***/

/* Write your code here */
(void)FRTOS1_xTaskCreate(Task1, (signed portCHAR *)"Task1", configMINIMAL_STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL);
(void)FRTOS1_xTaskCreate(Task2, (signed portCHAR *)"Task2", configMINIMAL_STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL);
FRTOS1_vTaskStartScheduler();

/*** Don't write any code pass this line, or it will be deleted during code generation. ***/
/*** Processor Expert end of main routine. DON'T MODIFY THIS CODE!!! ***/
for(;;){}
/*** Processor Expert end of main routine. DON'T WRITE CODE BELOW!!! ***/
} /*** End of main routine. DO NOT MODIFY THIS TEXT!!! ***/

/* END ProcessorExpert */
/*
** ###################################################################
**
**     This file was created by Processor Expert 5.3 [05.01]
**     for the Freescale HCS08 series of microcontrollers.
**
** ###################################################################
*/

Building the Application

I use select the project in the Project Panel view and use the menu Project > Build Project to compile and link it. This should pass without errors and warnings.

Downloading and Debugging

Finally, time to run it. For this again I have the project folder selected and use the menu Run > Debug. Running the application, and now I should see my two LED’s blinking :-).

Summary

Adding an RTOS to a microcontroller application is usually not easy. If I do not have an example for my board and microcontroller, then this can get time consuming and complicated. With Processor Expert and the FreeRTOS component I have a graphical UI to configure all the important settings (stack, heap, software interrupt and tick timer). And because Processor Expert generates all the RTOS source files and configuration files for me, this makes it really simple and easy.

Further Information…

As a starter, I suggest to have a look Quickstart for Processor Expert in Eclipse. This gives a head start on some aspects of using Processor Expert.

For more information about FreeRTOS and the API, have a look at the  FreeRTOS documentation on the web.

Happy FreeRTOSing with Processor Expert 🙂