Posix GCC Eclipse FreeRTOS 5.3.0 Simulator

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

Changelog:
	22/06/2009 - Fixed a bug regarding re-enabling of interrupts when a
task previously had them disabled.
	- Implemented vPortSetInterruptMaskFromISR and
vPortClearInterruptMaskFromISR to enable the use of FreeRTOS system calls from
interrupt handlers (Signal handlers which interact with queues).
	- Changed the Signal Handler masks so that other signals can be used 
without having to change port layer code and signals will act more like
interrupts.
	- Changed the tick to be the real-time tick and added code in main.c 
that makes the process far more agreeable. The process will no longer steal all
of the host OS idle time but will still run in pseudo real-time.


Introduction:
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_REAL because it most closely
matches the real-world timing. ITIMER_VIRTUAL 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.

To prevent the process from stealing all of the Idle excution time of the Host OS, nano_sleep()
can be used because it doesn't use any signals in its implementation but will abort from the 
sleep/suspending the process immediately to service a signal. Therefore, the best way to use it
is to set a sleep time longer than a FreeRTOS execution time slice and call it from the Idle task
so that the process suspends until the next tick.

All feedback is welcome.
