| 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. |