Documented which benchmarks/apps are shipped with MetalSVM and what they

do/how to configure them.

documentation/text/benchmarks.dox

@@ -0,0 +1,161 @@
+/**
+ * @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.
+ *
+ *
+ */
+

documentation/text/tasks.dox

@@ -108,7 +108,7 @@ static int foo(void* arg)
  * \c make in the project directory.
  *
  * The initrd building scripts include every file within the \c newlib/examples/ 
- * directory which is marked as \b execuable. Do not forget this if you use your
+ * directory which is marked as \b executable. Do not forget this if you use your
  * own build scripts!
  *
  * After providing your own executable for the system within the initial ramdisk,