metalsvm/documentation/text/benchmarks.dox

/**
 * @file benchmarks.dox
 * @page benchmarks Benchmarks and Example Applications
 *
 *
 * @section toc Table of Contents
 *  - @ref scc_ks
 *  - @ref general_ks
 *  - @ref general_us
 *
 * @section kernelspace Kernel Space Applications/Benchmarks
 * Located in: `apps/`
 * 
 * You can activate/deactivate the start of these applications after booting MetalSVM
 * using the \c \#define flags in `apps/tests.h`.
 * The configuration looks like (Just remove the comment prefix from the applications
 * you would like to start):
 * \code
 ...
//#define START_SVM_TEST
#define START_SVM_BENCH
//#define START_MAIL_PING
#define START_MAIL_NOISE
//#define START_KERNEL_LAPLACE
//#define START_KERNEL_JACOBI
 ...
 * \endcode
 * 
 * There are SCC-specific as well as generic kernel space applications and benchmarks.
 * Most of these applications are located in `apps/tests.c`, unless otherwise noted:
 *
 * @subsection scc_ks SCC-specific 
 * 
 * - __SVM_TEST__: This application creates three matrices A, B and C in 
 *   shared memory fields and calculates C = A * B.
 * 
 *   After calculation, it checks the result for correctness, compares execution 
 *   time between serial calculation and shared memory parallelization and prints 
 *   statistics about the different cores' access to shared pages.
 * 
 *   You can configure different SVM release consistency models: Set the 
 *   \#define-constant `SVM_TYPE` to either `SVM_LAZYRELEASE` or `SVM_STRONG`.
 *   The `GET_B(i, j)` macro can be configured to transpose the matrix rows and 
 *   columns.
 *
 * - __SVM_BENCH__: A benchmark for two executing cores.
 *
 *   At first some shared memory pages are allocated. The benchmark measures the 
 *   time the SVM implementation needs for creating and moving these pages between 
 *   the cores.
 *
 *   You can configure different SVM release consistency models: Set the 
 *   \#define-constant `SVM_TYPE` to either `SVM_LAZYRELEASE` or `SVM_STRONG`.
 *
 * - __MAIL_PING__: MetalSVM provides a mailbox system using the iRCCE library as 
 *   a foundation for communication between the SCC-cores. In this benchmark the 
 *   latency of intercore-pings is measured: This involves sending a a PING-message, 
 *   an intercore-interrupt, and waiting for the answer.
 *
 * - __MAIL_NOISE__: A high number of messages is sent from all cores to all cores to 
 *   generate noise on the on-die mesh.
 *
 *   Latency is measured, but this noise can also be used to check performance of 
 *   other applications under influence of noise.
 * 
 * - __KERNEL_LAPLACE__: This application iterates over a shared memory field with 
 *   the laplace differential equation solver. Execution time will be measured.
 *
 *   You can configure different SVM release consistency models: Set the 
 *   \#define-constant `SVM_TYPE` to either `SVM_LAZYRELEASE` or `SVM_STRONG`.
 *
 *   Location: `apps/laplace.c`
 *   
 * - __KERNEL_JACOBI__: A shared memory implementation of the jacobi matrix equation 
 *   solver. This is an interesting SVM example application, because besides 
 *   `svm_barrier()`, it also uses `svm_flush()` and `svm_invalidate()`.
 *
 *   You can configure different SVM release consistency models: Set the 
 *   \#define-constant `SVM_TYPE` to either `SVM_LAZYRELEASE` or `SVM_STRONG`.
 *
 *   Location: `apps/jacobi.c`
 *
 * - __ECHO__: Starts a new system thread providing an echo service over network 
 *   listening on port 7.
 *
 *   Location: `apps/echo.c`
 *
 * - **NETIO**: Measures the network throughput between two cores on the on-die mesh
 *   for different packet sizes.
 *
 *   This benchmark consists of 2 kernel space tasks.
 *
 *   Task 1 is the TCP server listening on port 18767. It will be started on RCCE 
 *   rank 2. As a reaction to commands from a client it will send/receive data and 
 *   measure the bandwidth of the transmission.
 *
 *   Task 2 is the TCP client started on RCCE rank 0. It connects to the server task
 *   and sends commands to send/receive data, doing the same performance measurements
 *   as the server task. 
 *   
 *   If the kernel is not configured for the SCC (`CONFIG_ROCKCREEK`), only the
 *   server task will be started. The client has to be started manually from elsewhere
 *   in this case.
 *
 *   A possibility to improve the performance is bypassing the socket interface.
 *   To do this, activate the \#define constant `USE_SOCKET_BYPASSING` in the same file
 *   to a value != 0.
 *
 *   Location: `apps/netio.c`
 *
 * @subsection general_ks Generic 
 * 
 * - __CONSUMER_PRODUCER__: A typical producer-consumer scenario testing the 
 *   semaphore mechanism. After some cycles of producing and consuming, messages are
 *   sent over the mailbox interface.
 * 
 * - __FOO__: A primitive kernel task example printing 5 kernel messages every second.
 *   Can be started multiple times to test the scheduler.
 *
 * - __JOIN_TEST__: A task starts a new child task executing the `foo`-example and
 *   and quits after the child task has executed using the `wait()` function.
 *
 * - __PI__: Serial calculation of pi.
 *
 * - __MEASURE_CTX_SWITCH__: Measures the pure overhead ticks of a context switch 
 *   between 2 kernel space tasks.
 *
 *   Both tasks continuously write the current TSC count to a shared variable until
 *   they are preempted and print the tick count the last context switch took.
 *   
 *
 * @section general_us Generic User Space Applications
 *
 * Located in: `newlib/examples/`
 *
 * - __MMNIF_TEST__: Starts a Server task on the first RCCE rank and
 *   a client task on every other rank. The clients request an example string 
 *   to print it afterwards, while the server keeps responding with this string.
 *
 *
 * - __hello__: Prints all environment variables and command line parameters. 
 *   Opens a test file, writes an example string to it, reads the same string 
 *   out again and afterwards prints the first directory entry of the `/bin` 
 *   directory.
 *
 * - __jacobi__: A usual jacobi matrix solver application. Measures its execution time.
 * 
 * - __mshell__: The M(etalsvm)shell provides basic commands to navigate through 
 *   the file system, print out files and start applications.
 * 
 * - __rlogind__: Started after boot by default, the rlogin daemon listens to port 4711.
 *
 *   It pipes stdin and stdout over network, making shell access over telnet possible.
 *
 * - __tests__: Initiates a fork, where the child task starts an instance of the 
 *   `hello` application with custom environment variables and command line parameters.
 *   The parent process waits for the child process to exit.
 *
 *
 */