From 5cc03d2ff6c1cf1bd2489705a7ce7c63079193af Mon Sep 17 00:00:00 2001
From: adrianogarcia <adriano.garcia@edu.pucrs.br>
Date: Tue, 23 Nov 2021 01:15:50 -0300
Subject: [PATCH] More content on how to run

---
 docs/source/how_to_run.rst | 110 ++++++++++++++++++++++++++++++++++++-
 docs/source/index.rst      |   3 +
 2 files changed, 112 insertions(+), 1 deletion(-)

diff --git a/docs/source/how_to_run.rst b/docs/source/how_to_run.rst
index 8d25acc..4c9e2f8 100644
--- a/docs/source/how_to_run.rst
+++ b/docs/source/how_to_run.rst
@@ -79,4 +79,112 @@ The table bellow shows all commands that can be used through the CLI.
 | **list_input** | It lists all inputs registered for a given application and their respective alias.<br />         | ``-app <SPBench_application>``(optional)                  |
 |                | (Attention: You can only use pre-registered alias after downloading the respective inputs.<br /> |                                                         |
 |                | See the section about inputs below).                                                             |                                                         |
-+----------------+--------------------------------------------------------------------------------------------------+---------------------------------------------------------+
\ No newline at end of file
++----------------+--------------------------------------------------------------------------------------------------+---------------------------------------------------------+
+
+How to use
+------------
+In this framework you can simply run the benchmarks that are already provided or implement your own specific benchmark.
+To run a given benchmark version, you can follow these steps:
+
+Run: ./spbench install (you can use -app <some application> to install only a specific application)
+Run: ./spbench register
+
+Run: ./spbench list (this shows the list of available benchmarks)
+Run: ./spbench compile -benchmark <benchmark_id>
+
+Run: ./spbench exec -benchmark <benchmark_id> -input <input_id> ... [optional_commands] <optional_args>
+
+
+To implement your own benchmark version, you must run new -> edit -> configure
+
+Inputs
+------------
+In the exec step you must choose a given input for the benchmark.
+These inputs can be found and downloaded in the inputs/ directory.
+You can run the 'get_inputs.sh' script to automatically download them.
+cd inputs/ && bash get_inputs.sh
+You can use your own input or choose a given one.
+You can also use an alias as short option.
+These alias are linked to the inputs provided by SPBench and you can see them running:
+./spbench list_inputs
+SPBench also allows you to create an alias for your custom inputs.
+./spbench new_input -input_id <input_alias> -app <spbench_application> -input "<full_path_to_your_new_input>"
+
+How to run example
+------------
+./spbench exec -version [version_name] -input [small, medium, large]
+
+
+Performance metrics
+------------
+With SPBench you can evaluate four performance metrics in different ways.
+- Latency
+- Throughput
+- CPU usage (%)
+- Memory usage (KB)
+
+Optional arguments
+------------
+
+There are four OPTIONAL arguments you can select when running the 'exec' command:
+
+- ``-monitor <time interval>``
+   It monitors latency, throughput, CPU and memory usage. Here you can indicate a monitoring time interval in milliseconds (e.g. 250.Optional). It will generate a log file inside a log folder (spbench/log/). This file will contain the results got for each metric at each time interval.
+
+
+- ``-latency``
+   It prints the average latency results for each application operator on the screen after the execution.
+
+
+- ``-throughput``
+   It prints the average throughput results after the execution.
+
+
+- ``-latency_monitor``
+   It monitors the latency per stage and per item and generates a log file inside the log folder.
+
+
+- ``-resource_usage``
+   It prints the global memory and CPU usage for the selected application.
+
+
+
+Other configuration arguments
+All of these are also OPTIONAL arguments that you can use within the 'exec' command.
+
+
+   - ``-in_memory``
+   It runs the application in-memory, which means that all the input is first loaded into the memory before start processing it. The opposite is true for the writing phase, where the result stays in memory and is only writen to the disk after all the input is proccessed.
+
+
+   - ``-nthreads <number_of_threads>``
+   Here you can define a number of threads to run the parallel versions. To be more preciselly, the degree of parallelism of the parallel stages (Obs.: some PPIs can create more threads than parallel stages). It shows up as a global variable that can be used inside the parallel versions.
+
+
+   - ``-batch <batch_size>``
+   Here you can change the size of the batches, so each item can carry more data. By default, the size of each batch is 1.
+
+
+   - ``-d``
+   This a specific argument for bzip2. You can use it to run this application in decompress mode. Observe that for de decompression mode it is required a compressed file as input (e.g. my_compressed_file.tar.bz2).
+
+
+
+Global attributes
+------------
+SPBench implements some global variables that can be used and modified by users in custom implementations. Some useful are:
+
+ - nthreads
+ - frequency (forthcoming): change the frequency of itens generated by source operator. The maximum is the speed of the memory access in your system. You can modify this
+
+
+Itens attributes
+------------
+
+All itens implements some attributes that you can use to build customizations.
+(forthcoming)
+
+.. Important::
+   You must run source setup_vars.sh to load the libraries.
+   You must load the libraries before using SPBench every time you star a new session!
+   To make FastFlow recognize and map the cores of the processor go into "/libs/SPar/libraries/ff/" and "/libs/fastflow/ff/" and run the "mapping_string.sh" script.
\ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 6a3afcc..f346f6c 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -50,6 +50,9 @@ Contents
 .. toctree::
 
    install
+   how_to_run
+   copying
    usage
    api
    download_links
+   about
-- 
GitLab