/**
\mainpage Overview

The libspe2 functionality is split into 4 libraries:
- <b>libspe-base</b> This library provides the basic infrastructure to manage 
and use SPEs. The central data structure is a SPE context spe_context. It contains all 
information necessary to manage an SPE, run code on it, communicate with it, and so on.
To use the libspe-base library, the header file <b>spebase.h</b> has to be included and 
and an application needs to link against <b>libspebase.a</b> or  <b>libspebase.so</b>.

- <b>libspe-event</b> This is a convenience library for the handling of events 
generated by an SPE. It is based on libspe-base and epoll. Since the spe_context
introduced by libspe-base contains the file descriptors to mailboxes etc,
any other event handling mechanism could also be implemented based on 
libspe-base. 

\section Terminology
- <b>main thread</b> usually the application main thread running on a PPE
- <b>SPE thread</b> a thread that uses SPEs. Execution starts on the PPE. 
                Execution shifts between PPE and an SPE back and fro,
                e.g., PPE services system calls for SPE transparently

\section use-case Usage Scenarios
\subsection single Single-threaded sample
Note: In the new model, it is not necessary to have a main thread - the 
SPE thread can be the only application thread. It may run parts of its
code on PPE and then start an SPE, e.g., for an accelerated function. The
main thread is needed only if you want to use multiple SPEs concurrently. 
The following minimalistic sample illustrates the basic steps:

\image latex singlemini.eps "Simple program" width=6cm

\include testsinglemini.c

Here is the same sample with some error checking:
\include testsingle.c

\subsection multi Multi-threaded sample
This illustrates a threaded sample using the pthread library:

\image latex pthreadmini.eps "Simple pthread program" width=6cm

\include testpthreadmini.c

Here is the same sample with some error checking:

\include testpthread.c

\subsection problem Problem state mapping samples

This illustrates accessing the MFC Local Store Address Register.

\include testmap1.c
\subsection event Event samples
This illustrates a sample using the event libary. The event, which we receive is of course
that the spu program has stopped, because otherwise we would not get there.

\image latex event1.eps "Simple event program" width=6cm

\include testevent1.c

Events are more useful in multithreaded environments:

\include testevent2.c

*/

/*
This illustrates a sample using the event libary.
\include testevent4.c

- <b>libspe-gang</b> This is a convenience library for SPE gangs. It uses libspe-base and 
pthreads to set up and run gangs of SPE threads. The main thread "sees" a single 
pthread for the whole gang of N plus N SPE contexts. As with libspe-thread, we need 
the SPE contexts explicitly to be able to use libspe-base.

- <b>libspe-thread</b> This is a convenience library that provides a pthread-based 
implementation of a thread model similar to libspe 1.1. In order to be able to use 
libspe-base functions, we need the SPE context associated with the pthread 

<b>NB</b>: In this version of the document, we concentrate on the <b>libspe base</b> part and eliminated all other parts temporarily.

\subsection gang Multi-threaded gang samples
This illustrates a threaded gang sample where the main thread starts all the spe threads:

\include testgang1.c

This illustrates a threaded gang sample with a gang master thread. The main thread 
only starts the gang thread, which in turn starts all the spe threads:

\include testgang2.c

\subsection thread Spethread samples

This illustrates a sample using the thread convenience libary.

\include testspethread.c

*/
 
/*
\image html cbea.png
\image latex cbea.png
*/