Homepage
The port is created using the wizC Integrated Development Environment from Forest Electronic Developments. The port can also be used with the FED C-compiler, also from Forest Electronic Developments. The difference between these two environments is the absence in fedC of the Rapid Application Development front end. This front end, however, is not used with this port. The port has been succesfully tested using version 11 (min. 11.04c) and version 12 (min 12.02e) of wizC and fedC.
Initially, the port and the demo applications were developed completely using only the wizC simulator. Hardware tests on real silicon did not start until all simulations ran without any problem. The final hardware tests turned out to be nothing more than a verification: All tests ran successfully on the PIC18F4620.
WizC and fedC are not free or open source products, but they do offer a very good price/performance. WizC professional also comes in a lite edition with attractive advantages for educational use.
The FreeRTOS source code download includes a comprehensive set of demo applications for the wizC/PIC18 port which are primarily designed to test the reliability and demonstrate the capabilities of this port.
As downloaded this demo application does not demonstrate the use of co-routines. See the co-routine documentation page for information on how co-routine functionality can be quickly added to this demonstration.
The Microchip PIC18 wizC/fedC port can be found in the FreeRTOS/Source/portable/WizC/PIC18 directory. In this directory you will find an installation script (install.bat). Please read the notes below before running this script.
Unlike the RTOS demo applications supplied with the other ports, the demo for this port is split into several smaller programs. This enables the demo's to be executed on the RAM challenged PIC18 devices. The demo applications can be found in the FreeRTOS/Demo/PIC18_WizC directory. Every application has it's own subdirectory. To load a demo-application into the IDE, double click the project file (eg. Demo1.pc).
FedC/wizC version 11: These libraries can be found in the directory Libraries/LibExt
on the fedC\wizC CD. Follow the directions in the pdf-file that comes with the libraries:
Running the setup is not all, some changes have to be made in the IDE. Especially mem.c must be
added as a library to the "16 Bit Core" tab in the IDE File/Libraries menu.
FedC/wizC version 12: The libraries are already installed and ready to use.
The port needs the malloc-library that is freely available from the user page on the Forest Electronic Developments website. The download file comes with it's own installation instructions and documentation.
The port needs the ANSI header files that are freely available from the user page on the Forest Electronic Developments website. The download file comes with it's own installation instructions and documentation.
The Microchip PIC18 wizC/fedC FreeRTOS port is designed to be a library in the wizC or fedC development environment. The library files need to be installed. The port source directory FreeRTOS/Source/portable/WizC/PIC18 contains a file called install.bat. This script will install all files needed to use the port in the LibsUser directory of your fedC or wizC installation. Double click the script to run it.
WizC and fedC have several optimization options in the project dialog box. Unless stated otherwise below, all options may be changed as desired.
The compiler can be instructed to use it's software stack or the PIC call stack to store the return address when a function is called. The FreeRTOS port requires the compiler to use the PIC call stack. When this option is not enabled, an error will be flagged during compilation. The call stack limits the calling depth to 32 levels. With FreeRTOS, every task has it's own 32 level call stack making PIC call stack overflows very unlikely.
The compiler can set global memory aside to be used for storing local variables and for passing parameters during function calls. This reduces the use of the software stack and, therefore, improves performance. With this port of FreeRTOS, the local optimise bytes can be freely used (or disabled). It is important, however, to realise that every task that runs under the RTOS has it's own copy of these local optimise bytes. At task switch, the 'locopt' area is saved to the task's stack. Thus, the size of the area affects the performance of task switches.
The compiler uses a heap to pass function return values larger than four bytes back to the calling function. For performance reasons, this port does not preserve the heap between task switches. It is therefore not allowed to have functions that return variables larger than four bytes. To help you avoid such functions, the FreeRTOS header contains a pragma to inform the compiler about this restriction. The compiler will then issue a warning when it encounters a function that uses the heap. Although only a warning is issued, you should not ignore this message because unexpected behaviour will occur. When you need to return variables (eg a structure) larger than four bytes, you should use a pointer to the structure instead.
The difference between wizC and fedC is the presence of a rapid application development front-end in wizC. This so-called Application Designer cannot be used with FreeRTOS and should be switched off for any project that makes use of this FreeRTOS port.
The FreeRTOSConfig.h file contains a definition called configMINIMAL_STACKSIZE to define the minimal size in bytes the stack for a minimal task should contain. By default for this port, configMINIMAL_STACKSIZE is defined as portMINIMAL_STACKSIZE. When you look for portMINIMAL_STACKSIZE in portmacro.h, you will find that the minimal stacksize is calculated during runtime upon the first reference of configMINIMAL_STACKSIZE. This is done because the minimal stacksize depends on several optimisation settings within your project. It is advised not to change the definition of configMINIMAL_STACKSIZE. If a larger stack is needed for one or more tasks in your project, use configMINIMAL_STACKSIZE as a base value:
#define MyStackSIZE ( configMINIMAL_STACKSIZE + 20 ) // MyTask needs 20 extra bytesThis way the automatic adjustment of your larger stack to the optimisation settings within your project still takes place. See the demo applications for examples of this feature.
Although, the PIC18 wizC\fedC port was developed entirely in the simulator, the anticipated hardware to run the demo applications was the 40 pin PICmicro prototyping board from Forest Electronic Developments. A PIC18F4620 embedded microcontroller was installed. This prototyping board allows for in system flash programming (ICSP) by means of the PicProg utility, also supplied by Forest Electronic Developments.
When using a different hardware platform, it is not very likely that this alternative board would have LEDs connected in the same configuration as the development board used to create the port. The LED routines are contained within FreeRTOS/Demo/PIC18_WizC/ParTest/ParTest.c and might require modification.The first demo is merely included to test the correct installation of FreeRTOS. It is meant to be run
only in the simulator because it blinks eight LEDs where the development board only has four. It can,
of course, be run on an alternative board which has eight LEDS on portD.
Eight tasks are created. Each task blinks a LED on portD. The blink rate of each task is chosen
in such a way that portD seems to be a binary counter. It are however eight independent tasks that
have been given convenient blink rates. This project is a good example of a minimal FreeRTOS project.
Includes the standard minimal "integer", "pollQ", "SemTest" and "Flash" tasks, along with a "check" task that periodically checks that the other tasks are operating without error, and flashes a LED accordingly. To ensure the target is not unexpectedly resetting a single "X" is transmitted from the USART when the application boots. When operating correctly Demo2 will cause LED 4 to toggle every 10 seconds. If an error has occurred in any task the toggle rate will increase to 1 second. A total of 12 tasks are created.
Includes the standard minimal "integer", "BlockQ" and "Flash" tasks, along with a "check" task that periodically checks that the other tasks are operating without error, and flashes a LED accordingly. To ensure the target is not unexpectedly resetting a single "X" is transmitted from the USART when the application boots. When operating correctly Demo3 will cause LED 4 to toggle every 10 seconds. If an error has occurred in any task the toggle rate will increase to 1 second. A total of 12 tasks are created.
Includes the standard minimal "integer", "dynamic" and "Flash" tasks, along with a "check" task that periodically checks that the other tasks are operating without error, and flashes a LED accordingly. To ensure the target is not unexpectedly resetting a single "X" is transmitted from the USART when the application boots. When operating correctly Demo4 will cause LED 4 to toggle every 10 seconds. If an error has occurred in any task the toggle rate will increase to 1 second. A total of 11 tasks are created.
Includes the standard minimal "flop" and "Flash" tasks, along with a "check" task that periodically checks that the other tasks are operating without error, and flashes a LED accordingly. To ensure the target is not unexpectedly resetting a single "X" is transmitted from the USART when the application boots. When operating correctly Demo5 will cause LED 4 to toggle every 10 seconds. If an error has occurred in any task the toggle rate will increase to 1 second. A total of 13 tasks are created.
Includes the standard minimal "ComTest" tasks, along with a "check" task
that periodically checks that the other tasks are operating without error, and flashes a LED accordingly.
When operating correctly Demo6 will cause LED 4 to toggle every 10 seconds. If an error
has occurred in any task the toggle rate will increase to 1 second. A total of 4 tasks are created.
Note: A loopback connector on the serial port is required to run this demo successfully.
Includes the standard minimal "Death" and "Flash" tasks, along with a "check" task that periodically checks that the other tasks are operating without error, and flashes a LED accordingly. To ensure the target is not unexpectedly resetting a single "X" is transmitted from the USART when the application boots. When operating correctly Demo7 will cause LED 4 to toggle every 10 seconds. If an error has occurred in any task the toggle rate will increase to 1 second. Demo7 repeatedly creates and deletes tasks up to a maximum of 10 tasks at one one time.
Each demo application directory contains it's own project file. A project is loaded into the wizC or fedC IDE by double clicking the project (.pc) file. After loading is complete, you can compile the project in the normal way.
A project consists of several files:
This file contains the main application code for the demo, including the main() entry point.
The configuration settings for the chip this demo will run on.
The PIC18 MCU supports only a single interrupt vector (priority interrupts are not used by the port). All interrupt handling is therefore concentrated in a single Interrupt() function which is located in this file. If additional handlers are needed, they can be added to this file. Several demo's make use of this facility.
The FreeRTOS configuration settings for this project. See the Customisation section for an explanation of all the settings.
The malloc library also has a configuration file. Things like the private malloc heap size are defined here. Refer to the documentation that accompanies the malloc library for more details.
Most demo applications use additional code from the FreeRTOS\Demo\Common\Minimal directory. To enable the compiler to locate the header files in FreeRTOS\Demo\Common\Include, WIZCmake.h contains a search path setting to this directory (If WIZCmake.h exists in the project directory, it is automatically included by the compiler as first header file with every compile).
The demo project in the FreeRTOS\Demo\PIC18_WizC\Demo1 directory is a very minimal project. The most simple way to start a new project is to copy all files from this directory to your new project directory.
Configuration items specific to this port are contained in FreeRTOS\Source\portable\WizC\PIC18\portmacro.h. The constants defined in this file do normally not require any modification.
Application specific configuration items can be found in the FreeRTOSConfig.h file within each project directory. All definitions in this file may be modified.
The definition configTICK_RATE_HZ is used to set the frequency of the RTOS tick. The supplied value of 250Hz is useful for testing the kernel functionality but might be faster than your applications require. Lowering this value will improve efficiency. When a too low value is used, the compiler will flag an error. Using an MCU frequency of 40MHz (10MHz xtal with pll), the minimum rate is 20Hz. Lower MCU-frequencies allow for even lower tick rates.
Because it is unlikely that the scheduler for the PIC port will get stopped once running, vPortEndScheduler() will perform a MCU reset.
Only the GIE bit in the INTCON register is used. This means that the port does not currently support high/low priority interrupts.
Every project contains an interrupt.c file. The routines to test each interrupt flag can be added to the Interrupt() function in this file. It is also possible to #include these routines. Study the demo projects for more information.
Upon entering the ISR, the current context is always saved. It is, therefore, allowed to use the entire spectrum of the C language inside an ISR (exception: local variables, see below). If a context switch is desired, set uxSwitchRequested to pdTRUE. This makes the task with the highest priority that is ready to run candidate to be restored (activated) at ISR exit. See FreeRTOS/Demo/PIC18_WizC/serial for an example of ISR routines.
In the ISR, it is not allowed to use local variables. To overcome this limitation, use one of the following alternatives:
Selecting a different MCU from the Microchip PIC18 family is an easy task:
Set the definition configUSE_PREEMPTION within the FreeRTOSconfig.h file in the project directory to 1 (to use pre-emption) or 0 (to use co-operative).
The port uses a compare match on timer 1 to generate the RTOS tick. During compilation, the timer and compare values are automatically calculated to match the MCU clock speed.
The port uses the malloc library that can be freely downloaded from the Forest Electronic Developments website. See the documentation of this library for detailed API-specifications.
It should be noted that the serial drivers are written to test some of the real time kernel features. They are not intended to represent an optimised solution. The bit rate register settings are automatically adjusted according to the frequency the MCU runs on.