ulster.ac.uk

Embedded SystemsUsing FreeRTOS with MPLAB X and the

PIC32MX250F128B (and the DP32 board)

Ian McCrumSchool of

Engineering

FreeRTOS can be incorporated into your own projects by copying 3 C source files (tasks.c, queue.c and list.c ) and their associated header files into your project

or more if you want timers and some other extra functionality

You also need a couple of files from the portable sub directory of the FreeRTOS installation. These are specific to the version of your chosen microprocessor (and compiler) family. You also need a C source file that provides memory management - you are given a choice of 4 or 5 to pick from, you don’t have to write your own.

There are guidelines on the FreeRTOS.org website but these are generic.

Modern MPLAB X uses a particular folder structure and also a project navigator to keep track of all included files. In addition, because it uses the gnu compiler and assembler (xc32-gcc and x32-as) you can set options for these programs of where to search for header files.

These slides show one way of setting up a MPLAB X project to allow you to use FreeRTOS. It is not the only way.

Writing software using FreeRTOS and MPLAB X

http://www.freertos.org/Creating-a-new-FreeRTOS-project.html

Source Files

FreeRTOS is supplied as standard C source files that are built along with all the other C files in your project. The FreeRTOS source files are distributed in a zip file. The RTOS source code organisation page (link above) describes the structure of the files in the zip.As a minimum, the following source files must be included in your project:

FreeRTOS/Source/tasks.cFreeRTOS/Source/queue.cFreeRTOS/Source/list.cFreeRTOS/Source/portable/MPLAB/PIC32MX/port.c and port_asm.SFreeRTOS/Source/portable/MemMang/heap_1.c where ‘1' can be 1, 2, 3, 4 or 5.And various header files – in Source/include and Source/portable/MPLAB/PIC32MX/

If you need software timer functionality, then include FreeRTOS/Source/timers.c.If you need co-routine functionality, then include FreeRTOS/Source/croutine.c.

I copy files from FreeRTOS into the MPLAB X project foldersThey are less than 1MB in size

MPLAB’s user project directory structure• My MPLAB X projects live in a folder called MPLAB• Under this, each folder represents a separate project, e.g I

have one called frdp32• Under this is the usual frdp32.X folder that MPLAB X

creates.• In this frdp32.X folder lies my own source and header files.• Download and unzip FreeRTOS to a convenient location.• Copy across all of the Source folders and subfolders. I put

mine in the same folder as the frdp32 folder.• Go through this copied Source and delete what you don’t

need.

Needed Files & suggested structure

I couldn’t get the “include” directories to work for the assembler so as a workaround I placed a second copy of the ‘h file here (recopy it if you edit either)

heap_1.c is the simplest – use it when you do not dynamically create and destroy tasks or queues – see the comments in the original source (or the next slide)

You create the .h file.In practice copy and edit one from the demo sources. You’ll need to edit maybe 3 or 4 lines

Viewing the demo files is very useful to clue you in as to what is needed

Comment block from heap_1.c ( lines 67-73 ) The simplest possible implementation of pvPortMalloc(). Note that this implementation does NOT allow allocated memory to be freed again. See heap_2.c, heap_3.c and heap_4.c for alternative implementations, and the memory management pages of http://www.FreeRTOS.org for more information.

Picking the right memory management code

Picking the right memory management codehttp://www.freertos.org/a00111.html Memory allocation implementations included in the RTOS source code download

heap_1.cThis is the simplest implementation of all. It does not permit memory to be freed once it has been allocated. Despite this, heap_1.c is appropriate for a large number of embedded applications. This is because the majority of deeply embedded applications create all the tasks, queues, semaphores, etc. required when the system boots, and then use all of these objects for the lifetime of program (until the application is switched off again, or is rebooted). Nothing ever gets deleted.

• Can be used if your application never deletes a task, queue, semaphore, mutex, etc. • Is always deterministic (always takes the same amount of time to execute) and cannot

result in memory fragmentation. • Is very simple; and takes memory from a statically allocated array, meaning it is often

suitable for use in applications that do not permit true dynamic memory allocation.

Your edits of FreeRTOSConfig.h (it’s 159 lines long, I changed 6 lines…)

#define configTICK_RATE_HZ ( ( TickType_t ) 1000 )#define configCPU_CLOCK_HZ ( 4000000UL )#define configPERIPHERAL_CLOCK_HZ ( 20000000UL )// IMcC adjusted two lines above

#define configTOTAL_HEAP_SIZE ( ( size_t ) 14000 )// IMcC changed 28000 to 14000 (original file was for a PIC32MX with more RAM …)

// IMcC set line below to 0 from 3#define configCHECK_FOR_STACK_OVERFLOW 0

// IMcC set line below to 0#define configUSE_MALLOC_FAILED_HOOK 0

Step by step details of setting up a MPLAB/FreeRTOS Project

Setup a project in MPLAB X as normal

Specify a standalone PIC project for the chosen PIC32MX, compiler and programmer.

This creates folders frdp32_1 and under that the folder frdp32_2.X

Open a file explorer window (or two)(I use the windows key and E to do this)

Copy the Source folder from the FreeRTOSV8.1.2/FreeRTOS installation to your project folder (the .X one)

To be tidy Delete the files below, (you don’t have to do this…)

I tend to keep all the files in the include directory though you probably only need half of them

Next find FreeRTOSConfig.h in the demo file in the PIC32MX_MPLAB folder as shown below

It would do you no harm to study the demo files in depth

However we can just as easily create a few much simpler examples using the DP32…

Copy FreeRTOSConfig.h to your .X folder and editMicrochip now suggest that it is better to use <xc.h> rather than a more cpu specific header file

File had 1 msec tick time, change if you want…

Match the PIC32MX250F128B on the DP32 hardware we use

Original demo used a PIC32MX460F512L, our PIC32MX250F128B has half the RAM so I arbitrarily reduced the heap. Experiment here once your code size (your data sizes) are known

Demo had functions for error checking, either disable them here or copy functions from the demo code to your own.

You now need to add source and header files to the MPLAB project

In the Projects Tab on the top left of MPLAB X, right click on “Header Files” and… Add item FreeRTOSConfig.h by browsing to your .X folderAdd item ISR_Support.h by browsing to your Source\portable\MPLAB\PIC32MX folderAdd item portmacro.h by browsing to your Source\portable\MPLAB\PIC32MX folderAdd Folder by browsing and selecting Source\include

In the Projects Tab right click on “Source Files” and… Add the files tasks.c from the Sources folderAdd the files queue.c from the Sources folderAdd the files list.c from the Sources folderAdd the files timers.c from the Sources folderAdd port_asm.S from the Source\portable\MPLAB\PIC32MX folder.Add port.c from the Source\portable\MPLAB\PIC32MX folder.Add heap_1.c from the Source\portable\MemMang folder

Select New->Main C file and name it e.g frdp32_2.c,you can paste in the code on the following slides into this to create content. Your final project should look like this

You now need to add include folder locations in the MPLAB projectIn the Projects Tab select the project name and select project properties and then xc32-as

1 Click on “Assembler Include Directories …

2 This window should appear, click on the blue area or browse and populate the window with the 3 directories shown, hit ok

3 You can confirm things by clicking on the “Generated Command line and check the text in the white box is sensible

4 NB you must click on the “APPLY” button below and wait a good 10 seconds until it has re-parsed the configuration files. Then move on.

Repeat for the xc32-gcc Include Directories

1 Pull down to set “preprocessing…

2 Click in the […] to set the Include directories

3 Add the three folders you see here…

4 You can confirm things by clicking on the “Generated Command line and check the text in the white box is sensible

5 NB you must click on the “APPLY” button below and wait a good 10 seconds until it has re-parsed the configuration files. Then Click this OK

Writing FreeRTOS

Source Code Slide 1 of 2

Writing FreeRTOS

Source Code Slide 2 of 2