The files under this directory compose the drmdump parsing framework
and applications.

Usage
=====

The main entry point is the "parseDumps.py" script.

usage:
$ python ./parseDumps.py --help
Usage: parseDumps.py [options]

Options:
  -h, --help            show this help message and exit
  -d DIR, --directory=DIR
                        root directory for dump files
  -f FILE, --file=FILE  dump file
  -o DIR, --output=DIR  directory to put generated files
  -t TOOL, --tool=TOOL  tool to run
  -s, --strict          proceeds with parsing only if we have a parser
                        available for the exact drmdump file version
  -v, --verbose         get more details about what the parser is doing
                        (mostly useful for debugging)

Parser
======

The "parsers" package provides an extensible set of classes to parse various
versions of the drmdump files.
For now, the set of available parsers cover:
- version 43 (VC 2.5.0 GA)
- version 103 (development version)

see parsers/v*.py for actual implementation

Adding support for a new version <X> means:
- provide a new v<X> module, with classes inheriting from those in v<X-1>
  module
- specialize the relevant classes for taking care of the latest changes
- add an entry in parsers/__init__.py to register the new parser

Tools
=====

Various tools can be plugged into the generic parser, to produce appropriate
results. A tool is mostly a visitor object, that will get called when the
relevant elements are parsed. This allows to decouple the parsing logic from
the analysis logic.

A trivial tool is "tools/dummy.py", that is able to visit all the parsed
elements, and reacts to none of them.
This tool can also serve as a base for more complex tools.

The tool "tools/simulator.py" aims at extracting relevant information from the
drmdump files, and generating input suitable for the DRS simulator, that would
simulate the same environment. As a consequence, we would be able to extract
test scenarios from "real-life" traces, and reuse them to investigate
improvements/regressions.

Running
=======
parseDumps.py is the top level script that can invoke any parsers and any
tools. Typical usage is

./parseDumps.py -t <tool name> -f <dump file name>

dummy tool doesn't print anything, but parses the dump file, can be a quick
check on whether the dump file is valid and can be parsed by this tool.

simulator tool currently prints the information about the dump file into a
bunch of text files and prints the stats information stats.d/ directory.

Gotcha: current tool doesn't run with 2.4.3 version of Python. Use the
toolchain version v2.7.1 for running.

Tests
=====

The "tests" directory should contain a set of dump files that cover as much as
possible the specificities of each file version.
This way, we can sanity check the parsing by simply running:
$ python ./parseDumps.py -d tests

Any regression in the parsing should make that execution fail.

TODO
====

* parse SDRS dumps
* parse mapVm files
* produce useful input for DRS simulator
