Managing The Etch Call Graph Profiler Profile Projects

Managing Etch Call Graph Profiler Projects

Keep your projects organized in project directories, with one directory for each profiled application. The Etch Call Graph Profiler creates some large files as a part of the instrumentation process. The largest files are usually the instrumented versions of the executable and DLLs. It's okay to delete these files if you won't be needing them again soon; they are easily regenerated by re-running cginstrument. The Etch Call Graph Profiler also creates a number of other files when you profile an application:

modules.bdb: A database of module used by the application
cgprof.mdb: static information used by the profiler
cgmon.output: raw profile data

The Module Database

The module database (modules.bdb) contains a list of all the modules used by an application that are known to Etch. For each module, the database describes a number of properties which specify how the module was instrumented. The module database is maintained automatically. There is no need to modify the module database manually. Nonetheless, an awareness and understanding of the module database may help you to understand more about how profiling works, and make it easier to diagnose problems when things go wrong.

The module database is stored as an ASCII file using the following formatting conventions:

	tool cgprof
	cautious no
	module modulename
		module-property
		module-property
		module-property
		...
	module modulename
		...

The first two lines describe the tool being run and must not be modified. They are followed by a single multi-line entry for each module that describes the following module properties.

rootmodule - yes/no [no default]
The rootmodule property is set for the module in a project that is used to launch the application. Normally the name for this module will end in .exe. Only one module per project will have the rootmodule property. This property is assigned by CGInstrument.
index - positive integer [no default]
Each module in a project has a unique module index. These are assigned by CGInstrument.
path [no default]
This specifies the fully resolved path name where the original of an executable module can be found. If CGInstrument has trouble finding an executable module, you can help it out by updating this property.
etchpath
The full path of the instrumented module.
etchname
The name of the instrumented module.

CGInstrument uses the following two flags to determine how to instrument the module.

codediscovery - 2, 1, 0 [default - 2]
This option specifies the aggressiveness of the algorithm Etch uses to distinguish code from data in an executable module. Reducing this value from 2 to 0 or 1 can sometimes eliminate runtime errors, but may result in a less accurate profile.
etchmoduletype - etch, patch, origbase, or special [default: etch]
This specifies how the module should be rewritten. This field is set by CGInstrument to one of the following values:
- etch - profile the module.
- patch - Do not profile the module. Do update its import table so that conflicts between profiled and original versions of DLLs are avoided.
- origbase - This is the same as the patch option except that the patched executable uses the same base address as the original. This is needed for system modules such as USER32.DLL, which can't be relocated due to addresses hard-wired into the operating system.
- special - Use the original version of the module at run-time without etching or patching. This option can only be used with a small number of special system DLLs.

Editing the module database (modules.bdb)

Normally you should not need to modify the module database by hand. There are certain cases though that do require you to modify properties for certain modules. Specifically, it is sometimes possible to eliminate a run-time error by changing the properties for the module in which the error occurs. You can edit the modules database with notepad or any text editor, provided you save it as an ASCII file. It is recommended that you make a backup copy of the database before editing it. If you do happen to corrupt your module database, recreating it is not hard; simply remove all files from the project directory and re-run cginstrument.

Controlling code discovery

In order to change the codediscovery property for a given module, change the integer value after the codediscovery property to 0,1 or 2. The example below shows how to change the module GDI32.dll from codediscovery 2 to codediscovery 0. The modifications have been highlighted in red.

Instrumenting the module with codediscovery 2: module GDI32.DLL path C:\WINNT\SYSTEM32\GDI32.DLL index 4 etchpath P:\project\ie\GDI32-ETCH.DLL etchname GDI32-ETCH.DLL etchmoduletype etch contextsave 48 codediscovery 2

Instrumenting the module with codediscovery 0: module GDI32.DLL path C:\WINNT\SYSTEM32\GDI32.DLL index 4 etchpath P:\project\ie\GDI32-ETCH.DLL etchname GDI32-ETCH.DLL etchmoduletype etch contextsave 48 codediscovery 0

Changing a module to be patched instead of instrumented

To change a module to be patched, you need to update the following properties:

etchmoduletype
etchname
etchpath

For each of these properties, change the string "etch" in the property value to "patch". The example below shows how to change the module GDI32.dll from instrumented to patched.

Instrumenting the module: module GDI32.DLL path C:\WINNT\SYSTEM32\GDI32.DLL index 4 etchpath P:\project\ie\GDI32-ETCH.DLL etchname GDI32-ETCH.DLL etchmoduletype etch contextsave 48 codediscovery 2

Patching the module: module GDI32.DLL path C:\WINNT\SYSTEM32\GDI32.DLL index 4 etchpath P:\project\ie\GDI32-PATCH.DLL etchname GDI32-PATCH.DLL etchmoduletype patch contextsave 48 codediscovery 2

Adding Modules to modules.bdb

Although it is sometimes useful to edit properties for existing modules by editing modules.bdb, you should never add modules to a project by editing the modules.bdb file directly.

The recommended method to add modules to modules.bdb is to run CGInstrument with the module name as the module argument. For example, to instrument notepad.exe, and then add winmm.dll as an additional DLL:

	cginstrument notepad.exe
	cginstrument winmm.dll

This will cause winmm.dll and all the DLLs it imports to be added to the module database. If you add winmm.dll by hand, the new DLLs imported by winmm.dll will not be added to the module database. This will typically result in a runtime error.

This same method applies to applications such as Direct Draw applications that use multiple executables. For example, to instrument the Direct-Draw game Monster Truck Madness (mtm.exe) and Direct Draw Help (ddhelp) in such a way that they use the same instance of ddraw.dll, you would do the following:

	cginstrument mtm.exe
	cginstrument ddhelp.exe

By instrumenting both programs in the same directory, you cause them to share the same module database, allowing the executables to share the same DLLs.