FreeRTOS Configuration
Bob continues his article series about the open-source FreeRTOS. All RTOSes need to be configured. This month Bob discusses the configuration parameters available to you to set up FreeRTOS.
Every real-time operating system (RTOS) I have ever incorporated into an embedded system required configuration. The very first was RSX-11 developed by David Cutler for Digital Equipment’s PDP-11 (Figure 1). (David went on to create Windows NT.) RSX stood for Real-time System Executive. These were the days when the designer put his name in the code, so David’s name was all over the source code. Once we had a problem with the RTOS and we called into DEC’s main number and asked for Dave Cutler. There was no such thing as Operating System Technical Support—so what the heck! Somewhat perplexed that we would call him, he asked us where we got his name. It seemed odd to us—since his name was everywhere in the code. But he was gracious enough to answer our question—and correctly!
Configuring an RTOS was a time consuming and grueling task—sitting at a LA36 DEC Writer printer console (see Figure 2—we didn’t have computer screens yet) and answering questions with a lot of guesses. If the data entry was not time consuming enough, our “powerful” development systems with 16k of memory would take hours to configure the software after we gave our semi-intelligent answers. While the computer was churning, there was not a progress bar widget letting us know our progress. Just an encouragement from the configuration program to take a coffee break. Curiously enough, when we configured RSX-11 in Britain, it told us to take a tea break.
SORTING OUT OPTIONS
From the looks of it, not much has changed when it comes to configuring FreeRTOS. It may not take much time to compile and we are not hunched over a printer console, but the number of parameters that we can set is significant and important. In this article, I will attempt to break down the major options for the configuration. Like RSX-11, configuration is done through a series of # defines (or the equivalent in PDP-11 assembly language) located in FreeRTOSConfig.h. Every demonstration app for every port has its own version of FreeRTOSConfig.h. Unlike RSX-11 (circa 1970) which had a configuration tool, as of today, FreeRTOS does not. This is not a giant problem—but I often wonder if some parameters are incompatible with others. For example, configuring FreeRTOS with a config file allows you to enable both the preemptive scheduler and the time slice scheduler. Clearly it is a mistake to do that, but what does the system do in that case? With freedom does come additional responsibility.
I am not a fan of the way FreeRTOSConfig.h is organized either. Every port has its own FreeRTOSConfig.h file in the port directory with different # defines—with the # defines in a different order—and often does not have all of them. For example:
configUSE_PORT_OPTIMISED_TASK_SELECTION
… is in the SAMA5 port but not the SAM9 port FreeRTOSConfig.h file—so we wouldn’t know there even was such a parameter from the source code if we just looked at the SAM9 FreeRTOSConfig.h file. Was it an oversight or can the SAM9 project not support this feature? We cannot tell.
— ADVERTISMENT—
—Advertise Here—
The FreeRTOS community recognizes the problem this presents and provides the following disclaimer:
Note, however, that some of the demo projects were generated before all the options documented in this chapter were available, so the FreeRTOSConfig.h header files they contain will not include all the constants and options that are documented in the following sub-sections [1].
Although that may be true, it could also be that the designers of a new port forgot a parameter. Or that the feature is incompatible with their port. A much better approach (if you don’t have a configuration tool) would be to have FreeRTOS release the FreeRTOSConfig.h with every parameter in it defined and documented with some default. My favorite example of this is the Apache web server configuration file: httpd.conf. It itself includes a hierarchy of include files. This file has the description of the file, the road map of the file and the syntax of the file. Each parameter has all the documentation for each parameter. For example:
#
#MaxKeepAliveRequests: The maximum number of requests to allow
# during a persistent connection. Set to 0 to allow an unlimited amount.
# We recommend you leave this number high, for maximum performance.
#
MaxKeepAliveRequests 100
The FreeRTOSConfig.h instead points you to the location on the website, which contains the definition of each parameter [2]. The reference manual [3] has basically the same information. (This 400-page document is very good, but I am a big fan of having all source information in one place.) How much better to derive the reference manual and website description from the source code using some tool like Doxygen [4].
WHAT CAN BE CONFIGURED
Enough of my ranting about what could be improved. Let’s see what options you have in configuring FreeRTOS (Figure 3). I have divided the options into the following categories: task and scheduler, queue related functionality, Inter Process Communication (IPC), software timers event and group parameters.
Before we launch into each of these, let me mention that there are several categories of configuration constants in FreeRTOS: those that start with “config…”, those that start with “INCLUDE…”, those that start with “configUSE…” and those that start with “port…” Just to confuse you, there are also two parameters that are “configINCLUDE…”
Constants that start with the text “INCLUDE…” are used to include or exclude FreeRTOS API functions from the application. This will add a lot of extra unnecessary work and clutter if you have a modern linker. Almost all linkers don’t include modules that are not referenced—so these parameters have no impact on code size. I understand that the designers wanted to minimize code for older linkers, but you probably don’t need these parameters. I won’t take your time going over these and neither should you. Just include them all. Rant alert: These constants beg for a common FreeRTOSConfig.h file so that you never miss any functionality that gets added after your processor is ported.
Configuration constants that start with “configUSE…” are used to add a feature to FreeRTOS. For example, configUSE_MUTEX and configUSE_TIMERS. When defined, these don’t just add functions, but affect the operation of other functions.
— ADVERTISMENT—
—Advertise Here—
Configuration constants that start with “port” are parameters that are port specific but impact the kernel. For example: portSTACK_GROWTH. Some microprocessors grow the stack in the positive direction and some in the negative direction. It would be helpful for the operating system to know that! Unfortunately, the reference manual does not define these parameters. You must look them up in the code. Rant Alert: Have the code generate the reference manual. Thankfully, there are not a lot of them.
In addition, there are two parameters with configINCLUDE:
configINCLUDE_FREERTOS_TASK_C_ADDITIONS_H and
configINCLUDE_APPLICATION_DEFINED_PRIVILEGED_FUNCTIONS
The documentation is not clear why this fifth naming convention is used nor could I figure out the logic. Now lets look at each category of configuration parameters.
Task and scheduler configuration parameters: We touched on some of these in our last article. Table 1 provides all of the task related configuration parameters. As with all the tables that follow, this is a view from 5,000 feet. More detail is included in the reference manual unless otherwise specified in which case we will document it from what is in the source code. (Do your own Rant Alert on this one!)
Queue configuration parameters: Queues are used to communicate events and transfer data. We covered queues in my article “Concurrency in Embedded Systems (Part 5)” (Circuit Cellar 271, February 2013) [5]. Table 2 defines the parameters with which you configure queues.
Inter Process configuration parameters: Additional IPC configuration parameters (MUTEXES and semaphores) are shown in Table 3.
Software timer configuration parameters: FreeRTOS uses a privileged kernel task to manage software timers. Table 4 documents these parameters.
Event configuration parameters: To create an event driven application using FreeRTOS, the event grouping configuration parameters defined in Table 5 will customize this functionality for you.
Port configuration parameters: Port parameters that effect the kernel are defined in Table 6. There are many other port specific parameters for each individual port.
CONCLUSION
FreeRTOS is small enough to be able to document it in a way for one person to fully understand its functionality. Even so, the Reference Manual is 400 pages long and the official tutorial is 399 pages long! Next time, we will look at the Inter Process Communication available in FreeRTOS—but only in thin slices.
RESOURCES
— ADVERTISMENT—
—Advertise Here—
References:
[1] https://www.freertos.org/fr-content-src/uploads/2018/07/FreeRTOS_Reference_Manual_V10.0.0.pdf[2] See http://www.freertos.org/a00110.html
[3] https://www.freertos.org/fr-content-src/uploads/2018/07/FreeRTOS_Reference_Manual_V10.0.0.pdf
[4] https://www.doxygen.nl/index.html If you don’t know about this tool, you should. There are others, but we have used this for years. It has clear and clean definitions and flexible outputs.
[5] Embedded in Thin Slices: Part 5 of Concurrency in Embedded Systems series in Circuit Cellar February 2013 Issue 271
FreeRTOS | www.freertos.org
PUBLISHED IN CIRCUIT CELLAR MAGAZINE • APRIL 2021 #369 – Get a PDF of the issue
Sponsor this Article
Bob Japenga has been designing embedded systems since 1973. From 1988 - 2020, Bob led a small engineering firm specializing in creating a variety of real-time embedded systems. Bob has been awarded 11 patents in many areas of embedded systems and motion control. Now retired, he enjoys building electronic projects with his grandchildren. You can reach him at
Bob@ListeningToGod.org
