File	Date	Author	Commit
libs	2011-03-08	Lukas Czerner	[959ce4] Replace linked list by rbtree
results	2010-02-12	Lukas Czerner	[863905] Added helpers for creating results.
.gitignore	2010-02-01	Lukas Czerner	[8e6952] Initial Import
LICENCE	2011-03-09	Lukas Czerner	[0ba7b7] Change licence to GPL 2
Makefile	2011-03-08	Lukas Czerner	[959ce4] Replace linked list by rbtree
README	2010-10-18	Lukas Czerner	[4f3af0] Add LICENCE. All licence notice info files.
plot.dis	2010-02-09	Lukas Czerner	[345c8c] Gnuplot script updated.
test-discard.c	2011-03-08	Lukas Czerner	[959ce4] Replace linked list by rbtree
test-discard.sh	2010-02-02	Lukas Czerner	[f6eea5] Readme updated, plotting script updated.

Read Me

#######################################################################
# (C)2009 Red Hat, Inc., Lukas Czerner <lczerner@redhat.com>

This is a simple tool for benchmarking device discard (TRIM) performance.
According to benchmark parameters the tool will repetitively call
BLKDISCARD ioctl on the specified device with specified parameters
collecting performance statistics.

You can specify several parameter for the test. First of all you can
specify the overall amount of Bytes to discard, the bigger the value is,
the bigger discard ranges you can test, the more precise result you will
obtain, and the longer will the test take. Then you can specify device
LBA to start with discard test and record size. There are three modes
of the test: sequential test, random I/O test and test where we are
discarding already discarded blocks.

There is also support for automated testing of range of record sizes.
You just need to specify starting, ending and step record size and the
tool will automatically survey the whole range. In addition you can get
more script-friendly output for using this tool in scripts.

There is script file "test-discard.sh" which you can invoke whit just
one parameter [-d]. It is intended to be an easy way to run the test. It
also generates nice graphs from the output, but you must have gnuplot
installed.

#######################################################################
# Function Principle

Invoke ioctl with BLKDISCARD flag and defined range repetitively until 
the specified amount of data is discarded. Running time of each ioctl 
invocation is measured and stored (also min and max) as well as number 
of invocations and range size. From collected data we can compute 
average ioctl running time, overall ioctl running time (sum) and 
throughput.

In random IO mode discard range is not determined sequentially but
picked randomly anywhere on the disk, but it is of course aligned to
the range_size. Already discarded blocks are stored in the list. Before
each discard operation random block is generated and added to the list,
possibly altered if the block was already discarded. There is one 
limitation though, if the record size is to low and disk size is too
high, only a part of disk will be used. To be specific :

	max_tested_disk_size = INT_MAX * record_size;

This means, that with 4kB record_size you can use disk up to 8TB, at 
least on x86_64.


#######################################################################
# usage: 

<program> [-h] [-b] [-s start] [-r record_size] [-t total_size] 
[-d device] [-R start:end:step] [-z]
	
-s num Starting point of the discard
-r num Size of the record discarded in one step
-R start:end:step Define record range to be tested
-t num Total amount of discarded data
-d dev Device which should be tested
-b     Output will be optimized for scripts
	
 <record_size> <total_size> <min> <max> <avg> <sum> <throughput in MB/s>

-z     Discard already discarded blocks
-x     Run test witch random IO pattern [-s] will be ignored
-h     Print this help

\"num\" can be specified either as a ordinary number, or as a
number followed by the unit. Supported units are
	k|K - kilobytes (n*1024)
	m|M - megabytes (n*1024*1024)
	g|G - gigabytes (n*1024*1024*1024)

#######################################################################
# Files:

Makefile			# makefile
test-discard.c		# source codes
test-discard.sh		# run this script to start testing immediatelly, it 
					  also generates a graphs
plot.dis			# batch file for the gnuplot
README				# this readme

#######################################################################
# Examples:

./test-discard -s 10k -r 4k -t 10M -d /dev/sdb1
start : 10240
record_size : 4096
total_size : 10485760
device : /dev/sdb1

./test-discard -t 100m -R 4k:64k:4k -d /dev/sdb1
start : 0
record_size from 4096 to 65536 with the step 4096 is tested.
total size : 104857600
device : /dev/sdb1

./test-discard -t 50m -R 4k:1024k:4k -d /dev/sdb1 -b
This is the same as above but output will be more script friendly.
Output will be like:

4096 10485760 0.000054 0.143009 0.089510 229.145599 0.043640
8192 10485760 0.000060 0.155563 0.086155 110.278017 0.090680
12288 10485760 0.088581 0.179759 0.099331 84.828429 0.117885
16384 10485760 0.077438 0.177407 0.092211 59.015074 0.169448
20480 10485760 0.076724 0.142325 0.087052 44.570576 0.224363
...
...etc

See the help for description of those particular columns.

You can create graphs from this output directly, but you must have
gnuplot installed. Make sure that you have saved output to the file
named "output.dat". Then you can simple invoke:
	
	gnuplot plot.dis
	ps2pdf graphs.ps graphs.pdf

The easiest way to run the test is :

	./test-discard.sh -d /dev/sdb1

The script will handle the rest, even creates graphs. The testing
options in this case are identical to the example above, so pe patient
this will take a while.

#######################################################################
# Licence:

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.