Name: Hou, Binbing
Project: PA-1 (Simplebench)
Instructor: Feng Chen
Class: cs7700-sp18
LogonID: cs7700xx 

/****************************************Introduction**************************************/

This is a program project for the course CSC 7700 Advanced Storage Systems, Spring 2018.
The purpose of this project is to develop a simple storage benchmark tool that generates 
different types of workloads to drive the performance tests on a disk drive. 

The rest of the README file consists of three parts:

Part 1: Run and compile the codes
Part 2: The structure of the source code files
Part 3: Additional descriptions

/******************************Part 1: Run and compile the codes*************************/

The tool is super easy to use.

(1) To compile, just use the make command: $ make  
(2) After successfully compiling, you will get an executable file (the benchmark tool): simplebench
(3) For using the tool, nine parameters have to be correctly set.

The tool is driven by the parameter settings as follows:
   
    ./simplebench -e <Duration (s)>          /*setting the duration of the test in seconds*/
                  -f <Device or File>        /*setting the target device or file*/
                  -r <Range (MBs)>           /*setting The accessible range in MB*/
                  -s <Request Size (KBs)>    /*setting the request size in K*/
                  -t <Type (Read or Write)>  /*setting the request tyep as Read (R) or Write (W)*/
                  -p <Pattern (Seq. or Rnd)> /*setting the pattern as sequential (S) or random(R))*/
                  -q <Num of Threads>        /*setting the queue depth (parallel threads, 1 to 32)*/       
                  -d <O_DIRECT or not>       /*setting the direct_io flag as (T) or not setting as (F)*/
                  -o <output trace>          /*setting the output trace file name*/

For example:

    $ ./simplebench -e 60 -f ./testfile -r 1024 -s 4 -t R -p S -q 4 -d T -o ./test.tr

    This command runs a test of 60 seconds to test the file ./testfile with 4 threads, 
    generating sequential, 4KB, direct I/O, read requests in the range of the first 1 GB 
    of the file, and produces an output trace file ./test.tr upon completion.

The output information printed on the screen includes the results calculated by different 
metrics (i.e., average latency, throughout, and bandwidth). Each line of the trace file 
presents the activity of each I/O request, following the format:
 
    [Timestamp] [Thread ID] [Type] [Offset] [Size] [Latency]
 
    Timestamp: The issue time of I/O (in seconds); the first request timestamp begins at 0.
    Thread ID: The ID of the thread generating this request Type R or W.
    Offset: The request offset (in unit of 512-byte sectors).
    Size: The request size (in number of sectors).
    Latency: The time of completing request (in milliseconds).

Notes:

(1) Parameter Settings

The parameters can be set in any order; but all of them have to be properly set.
Refer to the descriptions above for details. The tool will report the incorrect 
settings.

(2) Access permissions

The tool will check your permissions to test the target file or device. Before testing, 
make sure you have the permission to access the target file or device to be tested. 
For the trace file; make sure you have the permissionto create the file.  

(3) Interfernces of I/O tracing

The process of collecting I/O traces may interfere the testing process, therefore it is not 
proper put the trace file on the drive to be tested. In particular, when the trace file is 
not too large, it can be put in an RAM-based file system such as tempfs (e.g., under the 
directory "/run" on Linux OS). 

(4) Factors affecting the observed performance 

For using direct_io, the buffer has to be alligned with the memory page size; therefore, the 
observed performance may be different by using different operation systems.

In addition, directly writing a disk drive (especially with direct_io) may lead to system 
corruption if the system metadata on the drive was overwriten.

The functions used to issue read and write requests, such as read/write and pread/pwrite, 
may have different performance. Specifically, this tool uses the read/write functions.

/***************************Part 2: The structure of the source files*********************/

The project has eight source code files:

project
  |-- simplebench.h     --> contains all the declarations of the functions and data structures.
  |    |--- parameter.c --> defines the functions related to parameter parsing and checking.
  |    |--- stat.c      --> defines the functions related to collect and calculate the results.
  |    |--- thread.c    --> defines the functions related to the thread workers.
  |    |--- trace.c     --> defines the functions related to collecting the request traces.
  |    |--- utility.c   --> defines the utility functions such as permission check.
  |-- simplebench.c     --> defines the main fuction for flow control of the test.
  |-- Makefile          --> compiles the codes.

The source code files also contain abundant notes for easy use and understanding.


/******************************Part 3: Additional descriptions*************************/

The tool has several particular considerations:

(1) Roboustnes

The tool allows the users to set the parameters in any order, and checks the parameter 
settings; any incorrect setting will be reported.

The tool also checks the permissions of the user to access the target file or device to 
be tested, and the permission to create the trace file. 

(2) Memory consumption

The tool considers the memory consumption. The threads shares the read-only data structures  
during the test process. 

(3) Reducing thread competition 

The tool assigns each thread a private data structure to collect the request results 
(i.e., the number of the requests, the total request latency, and the request type), 
avoiding the overhead of thread synchronization caused by using a shared data strcture to 
collect the request results of all the threads. In addition, compared to calculating the 
values from the trace file, this design is much more efficient and can instantly print 
the results upon the test completition.

(4) Scalability

The framework of the codes and the design of the data structures make it very easy to 
add additional functions to the current project. For example, by simply specifying the 
thread worker as a read worker or a writer worker, we can easily extend the tool to
support mixed concurrent read and write requests.

(5) Maintenance

Abundant notes are added in the source code files; thus, it is easy to read and maintain
the codes, especially for the future extension.