Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | Overview of the RSTF workspace: rstf = RST Format |
2 | Russell Quong 11/2002 | |
3 | ||
4 | For a more upto date copy of this information see: | |
5 | /import/archperf/ws/rstf/rstFormat.tex | |
6 | or | |
7 | http://ppgweb.eng/archperf/rstFormat.html | |
8 | or | |
9 | http://ppgweb.eng/~quong/rstFormat.html | |
10 | ||
11 | A) Purpose: | |
12 | 1) The main purpose of this WS is to define the RST file format in rstf.h. | |
13 | Some secondary and/or deprecated definitions are in rstf_*.h | |
14 | ||
15 | 2) A secondary purpose is to define common RST utilities/code, including | |
16 | starter code and RST-to-RST filters. | |
17 | ||
18 | B) Guidance on updating this workspace | |
19 | 1) The file rstf.h defines RSTF. Many other programs use this file. So... | |
20 | - Try to avoid changing this file if possible. | |
21 | In the last 12 months (10/2001-10/2002), I bumped the version once. | |
22 | - Avoid breaking backward compatibility AT ALL COSTS | |
23 | There is considerable data in rstf 2.04-2.06 format. | |
24 | - The safest changes involve adding new rtypes or adding more constants | |
25 | to existing enumerations. E.g. filling out the register constants | |
26 | in the REGVAL_T:regtype[] | |
27 | - There is a Java port of RSTF, in the jrst workspace. A Perl script | |
28 | "parses" rstf.h and makes undocumented assumptions about | |
29 | the way rstf.h looks. Please try to conform to the existing style | |
30 | in the typedefs and enums. | |
31 | - I (RQ) have tried to be stingy in using rtype values. | |
32 | 2) If you must change rstf.h, bump the version number in rstf.h | |
33 | ||
34 | C) Version numbers (VN): Many "programs" have VN. Here is some guidance. | |
35 | - rstf | |
36 | version of the RST Format. Should not change often. | |
37 | The first record in an RSTF trace must define the version number | |
38 | If a new version of rstf breaks backward compatibility, increment | |
39 | the major version. | |
40 | - rstFilter | |
41 | updated when a filter is added or updated. Update freely. | |
42 | rstracer = (in rstracer WS) | |
43 | Reflects which version of the rst tracer. The version indicates | |
44 | what bugs/idiosyncrasies exist. | |
45 | Rstracer outputs both its own version number and the RSTF version num | |
46 | ||
47 | D) Basic programs and scripts. | |
48 | ||
49 | rstFilter.C | |
50 | Implemements many RST to RST filters (read stdin/file , write stdout). | |
51 | Typically you need to use several filters in a row. | |
52 | All error messages go to stderr. | |
53 | This code offers generic double-buffering on both input and the output, | |
54 | making is "easier" (hah) to do transformations that must | |
55 | look at several records. | |
56 | ||
57 | E.g. | |
58 | rstFilter -a filter-spec1 input-file | rstFilter -a filter-spec2 > output | |
59 | ||
60 | For fixing up the post [Atrace->RST] files, I run the two filters: | |
61 | ihash = add ihash values to the RST records | |
62 | addBrTarg = fill in branch target addresses. | |
63 | ||
64 | runRSTFilt.sh: | |
65 | convenient shell script driver for running rstFilter. Use this. | |
66 | E.g to fix up the post [Atrace->RST] files, | |
67 | runRSTFilt.sh -a 'ihash addBrTarg' [-u] raw.rst | |
68 | ||
69 | This generates the file out.final which is the final processed RST file ready for snapping. | |
70 | ||
71 | atrace2rst.C: | |
72 | convert Atrace to raw RST | |
73 | ||
74 | test-atr2rst.sh: | |
75 | test the conversion from Atrace to refined RST and shows how to do this. | |
76 | We currently run atrace2rst and then add BR targets. | |
77 | ||
78 | mksnaps.sh: | |
79 | sample script to create Round 1 snaps (VA only) for Aztecs from long RST files | |
80 | ||
81 | ~quong/bin/rq-snap_global.sh: | |
82 | snap the RST file | |
83 | ||
84 | -o . -p $snapdir -n $nsnaps -s $snaplen,$actualRSTsize,4 out.final > snap.log 2>&1 | |
85 | ||
86 | put the output in . | |
87 | put the snaps in a subdirectory $snapdir of . | |
88 | ||
89 | data-atrace: | |
90 | some sample traces I use for testing | |
91 | the link BMCSRC points to the source for the sort files. |