STM32 Microcontrollersjulien.elfa-systemes.com/perso/#6.1. Getting... · The project structure is as follows: ... (Cortex Microcontroller Software Interface Standard) headers that

STM32 Microcontrollers

Tutorial #x.x : Getting Started with FreeRTOS Rev : 0

Author(s) : Laurent Latorre Date : 19-09-2015

Contents 1. Open a sample project .................................................................................................................... 2

2. Include FreeRTOS source files ......................................................................................................... 5

2.1. Get FreeRTOS source archive .................................................................................................. 5

2.2. Prepare your project folder ..................................................................................................... 5

2.3. Import source files into CoIDE project .................................................................................... 8

2.4. Configure FreeRTOS according to your needs ....................................................................... 12

3. Your first multi-tasks program ...................................................................................................... 14

4. Debug with FreeRTOS+Trace ......................................................................................................... 17

4.1. Getting Recorder source files into the project ...................................................................... 17

4.2. Configure the Recorder ......................................................................................................... 19

4.3. Starting the Recorder ............................................................................................................ 21

4.4. Dump Recorder Data ............................................................................................................. 22

5. Using Percepio Trace Analyzer ...................................................................................................... 27

6. Summary........................................................................................................................................ 33

1. Open a sample project

The first step in to open a basic project that works with your target board and has all the required setup (CMIS headers, startup files, and standard peripherals libraries)

This tutorial provides such basic project for the STM429 Discovery board, but you can adapt to any existing MCU target or development board. Just start from a clean project with all the required files.

Unzip the archive “STM32F429 Discovery Template Project.zip” somewhere on your hard drive (preferably in your CoIDE project workspace if you have one). Rename the folder to something like “STM32F429 Discovery FreeRTOS” to remember the purpose of this project.

Open the file “STM32F429_Discovery.coproj” with CoIDE.

The project structure is as follows:

• cmsis group: contains the cmsis (Cortex Microcontroller Software Interface Standard) headers that provides low-level access function to the Cortex-M processor.

• cmsis_boot group: contains main STM32 header file, standard peripherals headers inclusion, and the boot (startup) procedures, including the clock scheme setup.

• stdperiph_lib group: contains a header and a driver for each of the MCU standard peripherals.

• BSP (Board Support Package)group: contains higher-level functions to address board-level devices such as LEDs, Buttons, LCD Touchscreen, and external SRAM.

Build the project. There should be no error or warning:

Then flash the target. You should see the green LED on, and a welcome message displayed on the LCD.

Open the main.c file and review the code. All the functions called for LED and LCD management are part of the BSP, which in turn makes use of standard peripheral library functions.

2. Include FreeRTOS source files

2.1. Get FreeRTOS source archive

Go to the FreeRTOS web site (http://www.freertos.org/). Find the download page and get the latest official release as a .zip archive. At the time of writing this tutorial, current FreeRTOS version is 8.2.2.

Unzip the archive into a location of your choice, and open the so-created folder:

2.2. Prepare your project folder

Open the FreeRTOS folder from the downloaded archive:

Copy (CTRL-C) the source folder. Then go into your project directory (for that, you can use the

link at the bottom of CoIDE ) and paste (CTRL-V) the source file. Then rename it as “FreeRTOS”)

Now go back into the FreeRTOS unpacked archive and open the demo folder:

Locate a demo folder that matches best our situation. Here, we have a demo for Cortex-M4 processor from ST (STM32F407ZG-SK). Although this is not exactly our target processor (STM32F429), this should be good enough to start with.

Open that folder and copy (CTRL-C) the FreeRTOSConfig.h file. Then paste it (CTRL-V) into your project folder which should now look like this:

It is time to perform some cleaning. Open the newly copied/renamed FreeRTOS folder and delete any file that is not a source .c file or a header .h file:

Then go into the include folder and do the same:

Go back up one level and descend into the portable folder. Here you will find toolchain-dependent source folders. Delete all those folders except GCC and MemMang:

Open GCC folder and delete all the existing subfolders exept the one that matches our target MCU (ARM_CM4F):

2.3. Import source files into CoIDE project

Now that we have removed useless files from the directory structure, import both FreeRTOS folder and FreeRTOSConfig.h file into CoIDE by drag & dropping these elements from windows explorer into the CoIDE project tab:

The project structure is now as follows:

You have to choose one among 5 memory management scenarios. The way memory is managed defines how memory is allocated to store kernel objects (tasks, queues, and semaphores) data, and how it is freed when objects are dynamically deleted. If you don’t want to delete kernel objects

dynamically, then you can choose heap_1.c which implements a robust static memory management scheme.

Delete from the project structure the files heap_2.c to heap_5.c using the contextual menu (right-click) from a selection:

The FreeRTOS group is now:

2.4. Configure FreeRTOS according to your needs

If you try to build the project now, you’ll probably get some errors. This is because the FreeRTOS config file (FreeRTOSConfig.h) was taken from a demo and should now be tuned to our toochain and specific needs.

Open FreeRTOSConfig.h in the editor and perform the following changes:

Few words on these edits:

• __ICCARM__ is a label used by another compiler (IAR), but still we need the SystemCoreClock variable declaration.

• Disable the hook features, otherwise you need to write your own implementation of hook functions (i.e. the functions that are called upon specific kernel events) o ‘Tick’ events can be hooked to vApplicationTickHook() o ‘Idle’ events can be hooked to vApplicationIdleHook() o ‘Stack Overflow’ events can be hooked to vApplicationStackOverflowHook () o ‘Malloc failed’ events can be hooked to vApplicationMallocFailedHook()

• Disable the TRACE_FACILITY feature. We will use this feature later, but for the moment let us keep it aside.

You also need to tell GCC that MCU does have a hardware Floating Point Unit (FPU) because some of

the FreeRTOS functions make use of it. Open the configuration tab , and change FPU option to FPU hard.

From now on, you should be able to build the project without any error or warning, and even

flash the target.

So far, FreeRTOS sources are embedded into the project structure, but as no call to FreeRTOS functions are performed from our application, the program still executes with no multitasking.

It is now time to write your first FreeRTOS multitask program!

3. Your first multi-tasks program

Open the main.c file in the editor

First, let us include all the necessary headers (for MCU, Board and FreeRTOS stuff):

Then declare Kernel objects (Tasks, Semaphores, Queues, Mutexes…). Here, we will go through a very basic example, running two basic tasks with no synchronization or communication mechanisms:

The main() function basically should perform some board level initializations, then create the kernel objects, and finally call the OS scheduler that should never returns.

The infinite loop is only there to capture an abnormal scheduler exit, in case this happens.

Next is the tasks implementation. When using a multi-task OS, each task is written as if it was a main program for itself, and therefore implements an infinite loop:

That’s it. You are done with your first FreeRTOS program !

Build the project . There should be no error or warning.

Flash the target and verify that the code behaves as expected.

4. Debug with FreeRTOS+Trace

4.1. Getting Recorder source files into the project

Browse into the FreeRTOS archive you’ve downloaded earlier in this tutorial and go into the \FreeRTOS-Plus\Source\ folder.

Copy the folder (CTRL-C) FreeRTOS-Plus-Trace into the clipboard.

Then paste it into your project folder:

Just as with FreeRTOS core code, let us perform some cleaning before importing the sources into CoIDE. Descend into your copy of the FreeRTOS-Plus-Trace folder and subfolders:

• Delete any file that is not a source .c file or a header .h file • Move the file trcConfig.h from the ConfigurationTemplate folder to the root of your project

folder (i.e. beside FreeRTOSConfig.h) • Delete the now empty ConfigurationTemplate folder.

Then import both FreeRTOS-Plus-Trace folder and trcConfig.h file into CoIDE by drag & dropping these elements from windows explorer into the CoIDE project tab.

Verify that your project file structure is correctly populated with these new items:

4.2. Configure the Recorder

Let us then configure the trace recorder for our target MCU. Open trcConfig.h file in the main editor, and perform the following edits:

Scroll-down the trcConfig.h file and take a look on the several options you can select for the recorder. For instance, let us increase the amount of memory allowed for the recorder to store kernel events:

This should allow the recording of about 4000 kernel events. Leave other options to their default value for the moment.

Now open FreeRTOSConfig.h file in the main editor and enable the TRACE_FACILITY feature:

Scroll-down to the end of the FreeRTOSConfig.h file and include the required Trace header. This has to be done AFTER other FreeRTOS definitions are completed, so do not place this header inclusion somewhere else:

We are done with the configuration of the Trace Recorder. Now we can use it.

4.3. Starting the Recorder

You may have notice that the recorder is set to record events from the point it is launched, until the record memory is full. This mode is defined in the trcConfig.h file by the line:

By increasing the memory allocation to about 4000 events, and given that our program is pretty basic with only two kernel objects, we should be able to records several seconds (maybe minutes) of code execution.

Let us start the recorder before any call to kernel functions. This way, we should be able to “spy” kernel startup procedures.

Edit the main() function as follows:

Build the project . There should be no error or warning. Flash the target and verify that the code still behaves as expected with no visible change from before (the two blinking LEDs).

4.4. Dump Recorder Data

Then, launch the debugger .

When the debugger is ready, make sure that you have some useful views opened. If not already opened, go to view menu and open the following tabs:

• Variables • Expressions • Memory •

In the Variables tab, click the Add Global Variables button

Then select the two following variable:

The RecorderData variable is in fact a structure holding many data. Unfold the variable and scroll down to monitor the number of recorded events:

So far, RecorderData is empty, which is normal because we did not start the program.

Step over (or F10) few lines of code until you reach the vTraceInitTraceData() calling line. Press F10 once more and look into the Variables tab. Data structure has been initialized using our settings (maxEvents = 4000).

Then get ready to start recording. You will (when I say so!) press the Run button (F5), then wait

for few seconds (something between 5s to 10s), and then Suspend the program execution (F9).

Now go!

If have done well, you should have a number of events recorded in the memory:

Here, we can see that 484 events have been recorded. This means that I could have wait 10 times longer before memory would have been full.

OK ! So now, how can we analyze these records better that trying to decode the memory content by hands (a hacker only reserved game)?

We will dump (transfer) the memory content into a file that is readable by a dedicated Trace Analyzer Software.

When you want to dump a memory segment, you need to know the range of addresses you want to read from. Fortunately, the Trace Analyzer Software is able to find its data in the middle of a large amount of RAM data. Nevertheless, the dumping process may be quite long if you save all the RAM range, and you will end-up with big files on your drive. For that reason, let us roughly locate the Recorder data into the MCU memory.

In the Expressions tab, click on the Add new expression sign and type &RecorderData:

This way, you get the RAM address of the beginning of the RecoderData variable segment. In this example, this address is 0x20012e6c but you may have something different.

Next, go to the Memory Browser tab and enter this address in the edit field. Then press the Go button.

Now click the Export button.

Set Format to RAW Binary.

Start address should be set correctly, so just fill up the Length field. Provide a comfortable length to make sure that all the recoder data will be included into the dump process (100 000 for instance).

Choose a path and a file name for the output (for instance “ram.bin” onto your desktop). Then click OK.

It may take few seconds to dump the memory into the file. You will see a progress bar:

When done, you can exit the debugger by pressing the Stop button.

5. Using Percepio Trace Analyzer

Launch the Percepio FreeRTOS+Trace program:

Go to menu File Open and select you ram.bin file.

If you have done well, you should be able to explore your code execution. In this example, we have more than 6 seconds of events recorded.

Time

Priority

Go to View Trace Details

Here you have a summary of all recorder events:

You can scroll (Mouse Wheel) and zoom (CTRL+Mouse Wheel) and get details on events. By dragging the mouse vertically you can measure time intervals (100ms between Task_2 executions):

Zoom at the very beginning of the time scale and select the (startup) task to view details of kernel events at startup (make sure all events are selected in the view filter):

By selecting a task in the left lane, you get detailed information regarding that task:

There are a number of other useful views to analyze your code performance. The CPU Load Graph reveals for instance that CPU is not used more that 0.1% (meaning that it is in Idle mode 99.9% of time). Not surprising given the simplicity of the example…

If you’re looking for an exhaustive overview or Trace Analyzer capability, take a look here:

http://percepio.com/docs/FreeRTOS/manual/

6. Summary

In this tutorial you have learned how to install, configure, and use FreeRTOS into a very basic two-tasks STM32F4 project.

In addition, you have included a Trace Recorder to further analyze the behavior of your multi-tasks code.