source: trunk/symbol_table/README.txt @ 3028

Last change on this file since 3028 was 2272, checked in by ksherdy, 7 years ago

Update readme.txt

File size: 2.9 KB
Line 
1Author: Ken Herdy
2Created on: May 17, 2012
3
4ABOUT
5
6    This project builds length sorted symbol table test driver(s)
7    to validate symbol table correctness and evaluate performance.
8
9    The test driver is structured to slurp and process an entire
10    'generated' CSV test file on execution.
11
12    Test files are generated using the python script
13    'test/gen_test_file.py' or 'test/st_test_file_generator.py'.
14
15    Test files:
16
17    (i) start with and delimit each symbol with a single comma character,
18    (ii) contain symbols characters defined by the the character class [-a-zA-Z0-9_:.],
19
20    WARNING:
21
22    Do not contain EOF characters. Avoid hand editing test files
23    within applications that append EOF characters,
24    such as gedit, or 'diff' tests report missing
25    newline differences.
26
27HOW TO BUILD
28
29    This project currently supports symbol driver
30    builds for the each of the following length group strategies.
31
32    id                  G(L) = L
33    div2                G(L) = ceiling(L/2)
34    logbase2            G(L) = logbase2(L)
35    div2_logbase2       G(L) = div2(L) if L < k, k is even else logbase2(L)
36    bit_byte            G(L) = 7 if L < 8 else G(L) = 0
37
38    This project uses a two stage build process.
39
40    Stage 1 - The root directory Makefile compiles parallel bit stream source files to C++.
41    Stage 2 - The src directory Makefile compiles generated C++ code.
42
43    --- PERF BUILD ---
44
45    Builds symbol table driver for performance profiling.
46
47    cd symbol_table
48    make {id, div2, logbase2, div2_logbase2, bit_byte}
49    cd pablo_out
50    symbol_table/src/Makefile make {id, div2, logbase2, div2_logbase2, bit_byte}
51    ./id ../test/pin/\(L,0,U\)+_1_1.test
52
53    For example,
54
55    make id
56    cd pablo_out/
57    make id
58    ./id ../test/pin/\(1_1000_50\)_\(2_1000_50\)_\(3_1000_50\)_\(4_1000_50\)_1_1.test
59    BOM 16: 1 (avg time: 43735 cyc/kElem) Cumulative: 1 (avg: 43735 cyc/kElem)
60
61
62    --- GID TEST ---
63
64    A rudimentary test that evaluates that the correct number of unique GIDs
65    are allocated for each *.test file in the test/pin directory.
66
67    For example,
68
69    make id
70    cd pablo_out/
71    make id_gid_test
72
73    .
74    .
75    .
76    (9_1000_50)_(10_1000_50)_(11_1000_50)_(12_1000_50)_1_1.test
77    Expected: 200
78    Actual: 200
79    .
80    .
81    .
82    All pass.
83
84    NOTE:
85
86    File format: (Length, Occurences, Unique)...(Length, Occurences, Unique)_1_1.test
87
88    --- DIFF TEST ---
89
90    For each *.test file in the test/pin directory:
91
92    (1) Resolves the unique symbol gid for each symbol.
93    (2) Writes the gid to the corresponding symbol starts position in the occurences array.
94    (3) Looks up the gid for each symbol start position.
95    (4) Generates an output file to the test/pout directory.
96    (5) Diffs test/pin against test/pout.
97
98    make id
99    cd pablo_out/
100    make id_diff_test
101
102    diff -rq --exclude=".svn" ../test/pin ../test/pout || exit 0
103
104    NOTE: No differences reported indicates all diff tests pass.
105
Note: See TracBrowser for help on using the repository browser.