= Procbench toolset =

== Introduction ==
Developed software is designed for testing different processors which 
are mostly suitable for the embedded networking applications, such 
a network router is. The tool measure run time for each algorithm with 
different configurations and different data sets. The configuration files 
and data set files are included with this package. For platforms without 
filesystem it can be build a binaries linked with test data.

== Algorithm description ==

Toolset is a set of algorithms prepared to test the performance of processor.
It includes algorithms implementing:

=== Longest Prefix Match (LPM) ===
Longest Prefix Match (LPM) is an operation essential for routing and IP 
packet classification. The operation itself represented as a trie structure 
leads to many memory accesses. To address this potential bottleneck there 
are many variations utilizing optimized and extended tries and hash tables. 
Still the number of memory access might be an issues and therefore it is 
important to test promising LPM implementations.

==== TreeBitmap (TBM) ====
TreeBitmap is based on a concept of a Trie. It assembles multiple nodes 
of the Trie into multinodes. Each of this node represents a full subtree 
of the same shape. The look up operation upon such a structure allows 
to traverse multiple tree-levels by a single memory access which reduces 
the number of total accesses per a complete look up. Moreover, it provides 
quite efficient  range encoding of the multinodes which saves memory 
consumption.

==== Shape Shifting Tries (SST) ====
Similar to TBM the SST modifies simple trie. It also assembles multiple nodes
in a multinode with the main difference that the shape of each subtree
represented by the multinode may be different to others and is stored in each 
multinode. This way a sparsely occupied tree may be represented more 
effectively which leads to fewer memory look-ups but higher computation 
requirements.

=== Filters ===
Effective filtering scheme is essential for application which processes only 
a portion of the whole traffic. The filter must be simple enough to deal with 
the full traffic rate and at the same time it has to consume only small amount 
of device resources. Generally, Bloom filters and their variants are considered 
very effective and have been proposed as a solution for many applications. 
The test inherently includes computation of Bob Jenkin's hash function 
(lookup3) with various seeds. The hash values are used as indexes to access 
the filter.

==== Bloom Filter (BF) ====
Bloom filter is a probabilistic datastructure that captures information about
the presence of a given element in a set which elements were previously 
fingerprinted into the datastructure. It provides a false answer in case when
the element was not fingerprinted but its fingerprint overlaps with 
fingerprints of others. The underlying datastructure is a one bit-wide array. 
An element is fingerprinted into the array by setting up ones at positions 
indexed by multiple hash functions computed on the key of the inserted element.
The query is performed by computing hashes on the queried element and 
inspecting bits at positions given by the hashes. If all bits are set up to 
one than the element has been inserted or it is a false positive with certain 
probability. Basic Bloom filter supports only insert and query operations. 
The removal of a fingerprint would invalidate other fingerprints as well.

==== Counting Bloom Filter (CBF) ====
This algorithm extends Bloom filter with the ability to delete an element
from a filter. CBF underlying datastructure is an array of counters (suggested 
bit length of a counter in literature is 4 bits). The fingerprint of an element
is inserted into the filter by incrementing counters at positions indexed by 
multiple hash functions whereas by decrementing the counters the element
is removed. If indexed counters are greater than zero then the element 
is present in the set. There are several parameters of both Bloom filters that
need to be set such as number of elements in the inserted set, number 
of bits/counters of the array, probability of false positive. During testing 
these parameters are set up to different values but clearly the whole parameter 
space cannot be evaluated.

=== Pattern Matching ===
The tests above are focused on network or transport layer. But many 
applications require to parse application layer or inspect packet payload. 
This usually constitutes of pattern or regular expression matching on fairly
large databases of expressions. We test an algorithm based on deterministic 
automaton as well as an algorithm based on combination of deterministic 
and non-deterministic automaton which promises better theoretical cost.

==== Delay Input DFA (DFA) ==== 
The algorithm is based on common deterministic finite automaton (DFA). 
It extends DFA with additional implicit transitions. Implicit transition 
is taken when no other transitions from the current state are allowed. 
The implicit transitions may reduce the total number of states necessary 
to represent the whole pattern database. The next state logic is encoded 
in a transition table. Upon each incoming character, one or more memory 
accesses are required into the transition table. The current state is saved 
in a register.

==== Hybrid FA (HFA) ====
Combines DFA and nondeterministic finite automaton (NFA). HFA utilizes NFA to
represent regular expressions and DFA to represent patterns. Such division 
allows to reduce number of states hence to reduce the state transition table. 
On the other hand, evaluation of NFA parts may require to evaluate potentially 
viable transitions.

=== Your algorithm ===
==== Comes here... ====


== Requirements ==

 1. Linux compatible (cross-)build system.
 2. Testing device with linux and basic libc funcions (printf, etc.)

== Instalation & Execute ==

There are several possibilities:

Run "make" to compile entire toolset. Binaries will print time, which is taken 
for processing data by algorithm.

Run "make output" for executables, that print output values instead of time.

Run "make PARAM=value" for parametrized compilation, 
eg. for optimalization: "make CFLAGS=-O2"

Run "make static" for build executables with test data. Binaries will be 
created in folder called "[test]/static/". In static mode test results will 
be equivalent to the version without linked data.

Run "./test.sh" to perform all tests.

Run "./test.sh wiki" to perform all tests and print output, that is in Wiki 
format.

== Files description ==

	Makefile	- Makefile to run and compile selected tests
	README		- This documet
	common - 	- Files for static/non-static conversion
	license 	- BUT license file
	lpm		- set of LPM tests
	filters 	- set of filtering tests
	patternmatch	- set of pattern matching tests
	test.sh		- script for running tests

Every testing set consist of its basic test folders, main test rutine and test script.

See product web page for more details:
http://www.fit.vutbr.cz/research/view_product.php.en?id=174

