FreeRTOS Emulator

An implementation of POSIX based FreeRTOS with the combination of SDL2 graphics. Aimed at providing an x86 emulation solution for teaching FreeRTOS to students without the need of embedded hardware. Used at the Technical University of Munich in the teaching of the "Embedded Systems Programming Lab".

Based on/inspired by the FreeRTOS (V5.X) simulator developed by William Davy. Updated to use FreeRTOS V10.5.0.

Checkout the Wiki page for a detailed Documentation!

Doxygen documentation can also be found on the GitHub Pages page.

Dependencies

All of the library dependencies written by me are pulled in as submodules automatically when CMake is run.

FreeRTOS Kernel

To keep a tight control of the kernel being run in the emulator, the kernel is pulled in from a fork of the upstream FreeRTOS/FreeRTOS-Kernel.

POSIX port

The port and portmacro files required for the FreeRTOS Kernel have been added to the kernel fork as a submodule, they can be found here.

Graphics Library

The graphics library used by the emulator can be found here and is based around the SDL2 graphics libraries.

State Machine

The emulator provides demo code, a portion of this is a state machine implementation to help users structure a state machine behind their RTOS tasks. Sources can be found here.

Linked List

The state machine implementation uses a linked list implementation found here.

Async IO

Asynchronous communications through POSIX message queues and sockets is possible via the ASyncIO library found here.

Debian/Ubuntu

Assuming that you have some basic utilities like make, cmake and git already installed, execute:

sudo apt-get install build-essential libsdl2-ttf-dev libsdl2-mixer-dev libsdl2-image-dev libsdl2-gfx-dev libsdl2-dev

Additional requirements for development:

# Depending on your OS version you might have to add the llvm-toolchain-4.0 APT source before
sudo apt-get install -y clang clang-tidy astyle cppcheck

Arch

sudo pacman -S sdl2 sdl2_gfx sdl2_image sdl2_mixer sdl2_ttf

Additional requirements for development:

sudo pacman -S clang astyle cppcheck

Windows/Mac

¯\(°_o)/¯

....install linux?

(See Wiki)

Building

cd build
cmake ..
make

For those requiring an IDE run

cmake -G "Eclipse CDT4 - Unix Makefiles" ./

to generate the appropriate project files to allow for the emulator to be imported into Eclipse.

We also includes templates for Configuring VSCode automatically. Run the following in the build directory to install them:

cmake -DUSE_IDE=vscode ..

Further Information: Development-Environment

Additional targets

Documentation

Doxygen documentation, found in the docs folder, can be generated from cmake/make by passing the variable DOCS=on and making the target docs.

cmake -DDOCS=on ..
make docs

Tests

In test.cmake a number of extra targets are provided to help with linting.

Git --check

make commit

Checks for whitespaces and empty lines.

Astyle Formatting

cmake -DENABLE_ASTYLE=ON ..
make format

Invokes the Astyle formatter.

Warning: The default version of CMake which is installed f.e. on Ubuntu 16.04 will throw an arror when running make to setup the bin/astyle binary. Please upgrade to a newrer version manually if required:

VERSION=3.16
BUILD=5
wget -q https://cmake.org/files/v$VERSION/cmake-$VERSION.$BUILD-Linux-x86_64.sh
mkdir /opt/cmake
sh cmake-$VERSION.$BUILD-Linux-x86_64.sh --prefix=/opt/cmake --skip-license --exclude-subdir
ln -s /opt/cmake/bin/cmake /usr/local/bin/cmake
rm cmake-$VERSION.$BUILD-Linux-x86_64.sh

Clang Tidy

cmake -DENABLE_CLANG_TIDY=ON ..
make tidy

Uses clang tidy to find style violations, interface misuse of bugs found via static analysis.

To generate a list of warnings/errors use the build target tidy_list and then view the file tidy.fixes.

CppCheck

cmake -DENABLE_CPPCHECK=ON ..
make check

Code analysis with CppCheck, focusing on undefined behaviour bugs.

Valgrind (memcheck)

cmake -DENABLE_MEMCHECK=ON ..
make memcheck

Memory checker.

Google Tests/Coverage

Coverage

cmake -DENABLE_COVERAGE=ON ..
make

Each sanitizer must be run stand alone, thus you cannot run them together.

Address sanitizer

cmake -DENABLE_ASAN=ON ..
make

Undefined behaviour sanitizer

cmake -DENABLE_USAN=ON ..
make

Thread sanitizer

cmake -DENABLE_TSAN=ON ..
make

All checks

The target make all_checks

cmake -DALL_CHECKS=ON ..
make

will perform all checks

Running

The binary will be created inside a bin folder. The emulator should be run from this folder becuase at the moment the Gfx libraries rely on hardcoded resource paths for things such as fonts. As such to run perform the following.

cd bin
./FreeRTOS_Emulator

Debugging

The emulator uses the signals SIGUSR1 and SIG34 and as such GDB needs to be told to ignore the signal. An appropriate .gdbinit is in the bin directory. Copy the .gdbinit into your home directory or make sure to debug from the bin directory. Such that GDB does not get interrupted by the POSIX signals used by the emulator for IPC.

If using an IDE, make sure to configure your debug to load the gdbinit file.

Tracing

Note: this is experiemental and proves to be unstable with the AIO libraries, it was used during development of the emulator and provides a novel function for small experiements, it should not be used for serious debugging of the entire emulator as this will cause errors.

Tracing, found in lib/tracer is instrumented using GCC's function instrumentation.

Running

cmake -DTRACE_FUNCTIONS=ON ..

will include the constructor, destructor and the needed __cyg_profile_func_xxx functions that are called upon entry and exit of any functions called during the execution of the program. These callback functions are implemented to log the function, caller and timestamp of each function calls, written to a file named trace.out. As the values written out are memory offsets and, as such, are not human readable the trace dump must be processed by the script readtracelog.sh which uses addr2line to convert the memory offsets into human readable function calls, done using the memory map of the compiled executable.

Example

Adding something like

+void printhello(void)
+{
+    printf("hello");
+}
+
 int main(int argc, char *argv[])
 {
+    printhello();

To your code and then compiling and running the executable, after passing -DTRACE_FUNCTIONS=ON to cmake of course, you will be presented with an output similar to

x 0x55e138f918a9 0x55e138f9fe4d 1587039262
e 0x55e138f92f72 0x7f2117466023 1587039262
e 0x55e138f92f34 0x55e138f92f99 1587039262
x 0x55e138f92f34 0x55e138f92f99 1587039262
e 0x55e138f918f0 0x7f2117bb242b 1587039262

After processing using the provided script sorcery, running something such as

./readtracelog.sh ../../bin/FreeRTOS_Emulator ../../build/trace.out

You will see a human readable output that logs the function entries and exit made in the program

Exit  trace_begin at 2020-04-16T14:14:22+02:00
Enter main at 2020-04-16T14:14:22+02:00, called from ?? (??:0)
Enter printhello at 2020-04-16T14:14:22+02:00, called from main (main.c:624)
Exit  printhello at 2020-04-16T14:14:22+02:00
Enter trace_end at 2020-04-16T14:14:22+02:00, called from ?? (??:0)

Note that the ?? visible in the output above are the result of the function instrumentation only being able to map to functions compiled using the -finstrument-functions compile flag. Extenal libraries etc are only linked against and not compiled using this flag, therefore they cannot be instrumented.