Ian McCrum
School of
Engineering
Embedded Systems
Using FreeRTOS with MPLAB X and the
PIC32MX250F128B (and the DP32 board)
ulster.ac.uk
Writing software using FreeRTOS and MPLAB X
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.
http://www.freertos.org/Creating-anew-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:
I copy files from FreeRTOS into
FreeRTOS/Source/tasks.c
the MPLAB X project folders
FreeRTOS/Source/queue.c
They are less than 1MB in size
FreeRTOS/Source/list.c
FreeRTOS/Source/portable/MPLAB/PIC32MX/port.c and port_asm.S
FreeRTOS/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.
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
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
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)
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)
Picking the right memory management code
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
http://www.freertos.org/a00111.html
Memory allocation implementations included in the RTOS source code download
heap_1.c
This 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
#define configCPU_CLOCK_HZ
#define configPERIPHERAL_CLOCK_HZ
// IMcC adjusted two lines above
( ( TickType_t ) 1000 )
( 4000000UL )
( 20000000UL )
#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 edit
Microchip 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 folder
Add item ISR_Support.h
by browsing to your Source\portable\MPLAB\PIC32MX folder
Add item portmacro.h
by browsing to your Source\portable\MPLAB\PIC32MX folder
Add 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 folder
Add the files queue.c
from the Sources folder
Add the files list.c
from the Sources folder
Add the files timers.c
from the Sources folder
Add 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 project
In 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 reparsed 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
4
You can
confirm things by
clicking on the
“Generated Command
line and check the text in
the white box is sensible
Add the three folders you see here…
5
NB you must click on the “APPLY” button
below and wait a good 10 seconds until it has reparsed the configuration files. Then Click this OK
Writing
FreeRTOS
Source Code
Slide 1 of 2
Writing
FreeRTOS
Source Code
Slide 2 of 2