Posix GCC Eclipse FreeRTOS 5.3.0 Simulator

Contributed by William Davy. william.davy@wittenstein.co.uk

This is a port that allows FreeRTOS to act as a scheduler for pthreads within a process.
It is designed to allow for development and testing of code in a Posix environment. It 
is considered a simulator because it will not keep real-time but it will retain the same
deterministic task switching.

Build Instructions
	Pre-requisites:
		make	(tested with GNU Make 3.8.1)
		gcc		(tested with gcc 4.3.2)
	Optional:
		Eclipse Ganymede
		CDT 4.0

If you have Eclipse and the CDT installed then you can simply import the project (copying
into the workspace or not). The project has Debug and Release build configurations and is
a Managed-make C executable project so the Project Properties define the contents of the
Makefile.

Alternatively, to build the executable without Eclipse and the CDT, simply 'cd' into the
Debug or Release directory and type 'make all'.

The compilation and execution have been tested in an IA64 Ubuntu 8.10 and i386 Debian 4.0
build environments (using standard packages). No changes are necessary between the 64 bit
and 32 bit builds.

Debugging using GDB.
The port layer makes use of process signals. The three process signals that are used are
SIGUSR1, SIGUSR2 and SIGVTALRM. If a pthread is not waiting on the signal then GDB will
pause the process on receipt of the signal. GDB must be told to ignore (and not print) the
signal SIGUSR1 because it is received asynchronously by each thread. In GDB type 'handle
SIGUSR1 nostop noprint pass' to ensure that the debugging is not interrupted by the signals.
The equivalent in Eclipse is achieved by using the 'Signals' view and getting the properties
of SIGUSR1 and de-selecting the suspend option.

If necessary, SIGUSR1 and SIGUSR2 can be re-defined to any other unused signals (such as the
real-time signals).

There are three different timers available for use as the System tick; ITIMER_REAL,
ITIMER_VIRTUAL and ITIMER_PROF. The default timer is ITIMER_VIRTUAL because it only counts
when the process is executing in user space, therefore, the timer will stop when a
break-point is hit. ITIMER_PROF is equivalent to ITIMER_VIRTUAL but it includes time
executing system calls. ITIMER_REAL continues counting even when the process is not executing
at all, therefore, it represents real-time which is not always useful because it makes the
tick with respect to time spent executing very aggressive.

Port-Layer Design Methodology Justification
A simple implementation of a FreeRTOS Simulator would simply wrap the platform native threads
and calls to switch Task contexts would call the OS suspend and resume thread API. This
simulator uses the Posix signals as a method of controlling the execution of the underlying
Posix threads. Signals can be delivered to the threads asynchronously so they interrupt the
execution of the target thread, whilst suspended threads wait for synchronous signals to
resume.

Typically, when designing a multi-threaded process, the multiple threads are used to allow for
concurrent execution and to implement a degree of non-blocking on IO tasks. This simulator uses
the threads not for their concurrent execution but solely to store the context of the execution.
Signals and mutexes are used to synchronise the switching of the context but ultimately, the
choice to change the context is driven by the FreeRTOS scheduler.

When a new Task is created, a pthread is created as the context for the execution of that Task.
The pthread immediately suspends itself, returning the execution to the creator. When a pthread
is suspended it is waiting in a call to 'sigwait' which is blocked until it receives a resume
signal.

FreeRTOS Tasks can be switched in two manners, co-operatively by calling 'taskYIELD()' or
pre-emptively as part of the System Tick. In this simulator, the Task contexts are switched by
resuming the next task context (decided by the FreeRTOS Scheduler) and suspending the current
context (with a brief handshake between the two).

The System tick is generated using an ITIMER and the signal is delivered (only to) the currently
executing pthread. The System Tick Signal Handler increments the tick and selects the next
context, resuming that thread and sending a signal to itself to suspend (which is only processed
when exiting the System Tick Signal Handler as signals are queued).

Known Issues
The pthread_create and pthread_exit/cancel are system intensive calls which can rapidly saturate
the processing time. The Common Demo code includes a Suicidal Tasks test which executes
successfully, however, if the test is the only test which is being executed the process slowly
grinds to a halt.

On single core systems, the process will consume all of the processing time. To make the system
more responsive include 'sched_yield();' in the Idle Hook and that will yield the process. Also,
the process can be 'renice'd to a lower priority level.

All feedback is welcome.
