FreeRTOS Configuration
Let us continue Bob’s open-source FreeRTOS series. All RTOS require configuration. In this article, Bob will discuss the configuration parameters available when setting up FreeRTOS.
Every real-time operating system (RTOS) I have integrated into embedded systems required configuration. The first was RSX-11, developed by David Cutler for Digital Equipment’s PDP-11 (Figure 1). (David later created Windows NT.) RSX stands for Real-time System Executive. At that time, designers would write their names into the code, so David’s name was everywhere in the source code. Once, when our RTOS had an issue, we called DEC’s main office asking for Dave Cutler. There was no such thing as operating system technical support back then—so who cares! He was a bit confused as to why we were calling him and asked how his name got there. We found it strange—because his name was everywhere in the code. But he generously answered our questions—and answered them very correctly!
Figure 1 – PDP-11
Configuring an RTOS is a time-consuming and arduous task—we had to sit in front of the LA36 DEC Writer printer console (see Figure 2—we didn’t have computer screens back then) and answer questions with a lot of guesswork. If data input itself was time-consuming, our “powerful” development system with 16k memory would take hours to configure the software after we provided semi-intelligent answers. The computer would be running at full speed, but there was no progress bar widget to show progress. The configuration program would just remind us to go grab a cup of coffee. Strangely, when we configured RSX-11 in the UK, it prompted us to go have a cup of tea instead.
Figure 2 – LA36 DEC Writer
Organizing Options
It seems that not much has changed in configuring FreeRTOS. Compilation may not take much time, and we no longer have to hunch over the printer console, but the number of parameters we can set is quite significant. In this article, I will attempt to break down the main configuration options. Similar to RSX-11, configuration is done through a series of #defines located in the FreeRTOSConfig.h file (or the equivalent definitions in PDP-11 assembly language). Each demo application for each port has its own version of FreeRTOSConfig.h. Unlike RSX-11 (circa 1970), which had configuration tools, FreeRTOS still does not have one. This is not a big deal—but I often wonder if certain parameters are incompatible with others. For example, configuring FreeRTOS with a configuration file allows both preemptive scheduling and time-slicing scheduler to be enabled simultaneously. Clearly, this is wrong, but what would the system do in this case? Freedom indeed comes with additional responsibility.
I also dislike the organization of FreeRTOSConfig.h. Each port version has its own FreeRTOSConfig.h file in the porting directory, containing different #defines (the order of #defines also varies), and often does not include all definitions. For example:
configUSE_PORT_OPTIMISED_TASK_SELECTION
…exists in the SAMA5 port version but not in the SAM9 port version—therefore, if we only look at the FreeRTOSConfig.h file for SAM9, we cannot tell from the source code whether such a parameter exists. Was it overlooked, or does the SAM9 project not support this feature? We cannot be sure.
The FreeRTOS community has recognized this issue and provided the following disclaimer:
But please note that some demo projects were generated before all options documented in this chapter were available, so the FreeRTOSConfig.h header files they contain will not include all constants and options documented in Section [1].
While this may be true, it is also possible that the designer of the new port forgot a parameter, or that the feature is incompatible with their port. A better approach (if you do not have a configuration tool) would be for FreeRTOS to release a FreeRTOSConfig.h file where each parameter is defined and documented with some default values. My favorite example is the Apache Web Server configuration file: httpd.conf. It itself contains a hierarchy of included files. This file includes descriptions of the included files, a roadmap of the files, and the syntax of the files. Each parameter contains its corresponding documentation. For example:
The FreeRTOSConfig.h file would point to the location on the website that contains the definition of each parameter [2]. The information contained in the reference manual [3] is essentially the same. (This 400-page document is excellent, but I would prefer to have all source code information centralized in one place.) Wouldn’t it be better to use tools like Doxygen [4] to extract reference manuals and website descriptions from the source code?
Configurable Content
I have said enough about what needs improvement. Let us look at the options available when configuring FreeRTOS (Figure 3). I will categorize these options into the following groups: task and scheduler, queue-related features, inter-process communication (IPC), software timer events, and group parameters.
Figure 3 – Configuring FreeRTOS is like adjusting a set of gears to make them interact and work together.
Before introducing these configuration constants one by one, I want to mention that there are several categories of configuration constants in FreeRTOS: constants starting with “config…”, constants starting with “INCLUDE…”, constants starting with “configUSE…”, and constants starting with “port…”. For ease of understanding, there are also two parameters starting with “configINCLUDE…”.
Constants starting with “INCLUDE…” are used to include or exclude FreeRTOS API functions in the application. If you are using a modern linker, this will add a lot of unnecessary work and confusion. Almost all linkers do not include unreferenced modules—therefore, these parameters do not affect code size. I understand that the designers want to minimize the code size for old linkers, but you may not need these parameters. I would not spend time explaining these parameters, and neither should you. Just include them all. Warning: These constants require a generic FreeRTOSConfig.h file so that you do not miss any features added after processor porting.
Configuration constants starting with “configUSE…” are used to add features to FreeRTOS. For example, configUSE_MUTEX and configUSE_TIMERS. Defining these constants not only adds functions but also affects the operation of other functions.
Configuration constants starting with “port” are port-specific parameters but affect the kernel. For example: portSTACK_GROWTH. Some microprocessors grow the stack upwards, while others grow it downwards. It is helpful for the operating system to know this! Unfortunately, the reference manual does not define these parameters. You have to look for them in the code. Warning: Generate a reference manual from the code. Thank goodness there are not many reference manuals.
Additionally, configINCLUDE has two parameters:
configINCLUDE_FREERTOS_TASK_C_ADDITIONS_H and
configINCLUDE_APPLICATION_DEFINED_PRIVILEGED_FUNCTIONS
The documentation does not clearly explain why this fifth naming convention is used, and I have not figured out the logic behind it. Now let us look at each category of configuration parameters.
Task and Scheduler Configuration Parameters: Some of these were mentioned in the previous article. Table 1 provides all task-related configuration parameters. As with all subsequent tables, this is a view from a more macro perspective. Unless otherwise noted, more detailed information is contained in the reference manual, in which case we will document based on the content in the source code. (Interested readers, please write your own Rant Alert article!)
Table 1 – Task and Scheduler Configuration
Queue Configuration Parameters: Queues are used to pass events and transfer data. We discussed queues in my article “Concurrency in Embedded Systems (Part Five)” (Circuit Cellar 271, February 2013) [5]. Table 2 defines the parameters required to configure queues.
Table 2 – Queue Configuration
Inter-Process Configuration Parameters: Other IPC configuration parameters (mutexes and semaphores) are shown in Table 3.
Table 3 – Inter-Process Configuration
Software Timer Configuration Parameters: FreeRTOS uses privileged kernel tasks to manage software timers. Table 4 lists these parameters.
Table 4 – Software Timer Configuration
Event Configuration Parameters: To create event-driven applications using FreeRTOS, the event group configuration parameters defined in Table 5 will customize this functionality for you.
Table 5 – Event Group Configuration
Port Configuration Parameters: Port parameters that affect the kernel are defined in Table 6. Each port has many other port-specific parameters.
Table 6 – Kernel Port Configuration
Conclusion
The documentation for FreeRTOS is concise enough for a person to fully understand its functionality. Even so, its reference manual is 400 pages long, and the official tutorial is 399 pages long! Next, we will explore inter-process communication available in FreeRTOS—but only in a rough introduction.