 |
 |
Using DynamoRIO
(c) Copyright 2002-2005 HEWLETT-PACKARD COMPANY
(c) Copyright 2002-2005 Massachusetts Institute of Technology
|
|
|
(c) Copyright 2002-2005 HEWLETT-PACKARD COMPANY
(c) Copyright 2002-2005 Massachusetts Institute of Technology
|
|
Remember: THIS IS BETA SOFTWARE! It's not bulletproof.
Here are the platforms we support:
We do not currently support these program features (but we plan to in the future, unless noted):
Many large programs work fine under DynamoRIO, including Microsoft Office, Adobe Acrobat Reader, Adobe Illustrator, Microsoft Accessories, Winzip, Mozilla, Microsoft Internet Explorer, etc.
There are some programs that do not work due to bugs in DynamoRIO. We are working on fixing these. Here is a list of programs that do not work properly:
Threads and signals are fully supported except for some corner cases:
A program running under DynamoRIO with the -stats option (see Runtime Options) that crashes may leave its shared memory containing statistics sitting around. Too many of these can cause problems. They can be cleaned up using the ipcrm command:
#!/bin/csh
foreach id (`ipcs -m |grep 0x0| awk '{print $2}'`)
ipcrm shm $id > /dev/null
end
Bugs other than those listed here should be reported to us.
Booting your machine with Run All turned on has the potential to crash the operating system. To recover you need to clear the Microsoft\Windows NT\CurrentVersion\Windows\AppInit_Dlls registry key, or delete the DynamoRIO shared libraries.
|
The Windows GUI is useful for launching applications under DynamoRIO, viewing statistics of currently running applications, and setting DynamoRIO's runtime options.
The main portion of the GUI window displays statistics for the currently selected process that is running under DynamoRIO. All such processes that were run with the -stats option (see Runtime Options) are listed in the listbox at the top of the window below the menus. The log file (see Runtime Options) for the currently running program is displayed at the bottom of the window. Pressing the Explore button will launch the Windows explorer at the directory containing the log file, making it easier to view it and any dynamorio_traces.log files.
The Run menu has two options: Run a single application, and Run All (note that Run All is disabled on Windows NT). Running a single application launches that application under the control of DynamoRIO. Setting Run All sets the registry key that DynamoRIO uses to inject itself into every new process that is created. Run All is dangerous! We haven't tested DynamoRIO on every program, and it does cause some programs to crash. Please be careful of what you run while you have Run All turned on. When you exit the GUI while you have Run All turned on it asks you if you want to turn it off, so you won't accidentally leave it on.
The most-recently run applications are listed at the bottom of the Run menu.
The Options menu allows for copying the displayed statistics to the clipboard. It also can launch two dialog boxes: one for setting DynamoRIO's runtime options, and another for setting the list of programs not to run while Run All is checked. Both of these are stored in environment variables (DYNAMORIO_OPTIONS and DYNAMORIO_IGNORE, respectively). Changing the variables locally will affect all programs launched through the GUI, but will not affect programs run outside of the GUI! Also, when the GUI is exited, the changes to the environment variables are lost. This is why there is a "Set Permanently" button on each of the dialogs. This does the same things as setting the variable using the Control Panel. However, this still does not propagate the new variable to already-running programs, unless they watch for notifications that environment variables have changed (as the Windows Explorer does).
The Library menu selects which library is used for injection into target applications. Note that the release library does not support the -stats option (see Runtime Options) and so any program run under the release build of DynamoRIO will not show up in the GUI's list of processes.
Unlike the Windows GUI, the Linux GUI is only a statistics viewer. Unfortunately we are only able to provide a version that requires various gnome libraries and may not run on all Linux distributions.
|
On Windows, the GUI shows the command line it is using when it launches each application. This is useful for determining the path to the target application as well as how to invoke the DynamoRIO injector. The injector's first argument must point to the DynamoRIO library to use (remember, there are three versions of it in this release). The rest of the arguments form the command line that would be used to launch the target application natively. Here is an example of launching notepad from bash inside a cygwin shell.
c:/dynamorio/bin/drinject.exe c:\\dynamorio\\bin\\debug\\dynamorio.dll c:\\WINNT\\system32\\notepad.exe
On Linux, we use the LD_PRELOAD environment variable to inject the DynamoRIO library into a target process. The dynamorio script can be used. It relies on the DYNAMORIO_HOME environment variable to find the initial injection library. Which DynamoRIO library proper is used can be specified by pointing to its containing directory with the DYNAMORIO_SYSTEMWIDE environment variable, or by passing -debug, -profile, or -release to the dynamorio script. Here's an example of usage:
/usr/local/dynamorio/bin/dynamorio -profile mybenchmark args
|
csrss.exe;winlogon.exe;emacs.exe;regedit.exe
|
The environment variable DYNAMORIO_OPTIONS contains flags that control the runtime behavior of DynamoRIO. The following is a list of the available DYNAMORIO_OPTIONS for all builds:
Binary dump format:
* top of file:
int linkcount_size # 0, 4 (32-bit counters), or 8 (64-bit counters)
* each trace:
int frag_id; # always 0 for release build
app_pc tag;
int entry_offs;
int num_exits;
int code_size;
uint num_bbs;
if num_bbs > 0 # tracedump_origins
foreach bb:
app_pc tag;
int bb_code_size;
byte code[bb_code_size];
endif
foreach exit:
int exit_cti_offs;
int exit_stub_offs; # for separate stub, this is NOT within trace!
app_pc target;
bool linked; # bool is 4 bytes
if linkcount_size > 0
linkcount_type count; # sizeof == linkcount_size
endif
byte code[code_size];
See the provided sample binary trace dump
reader for an example of how to disassemble a binary trace dump file.
Printing symbolic information for addresses is not yet supported, but will
be in a future release.
LOG_NONE 0x0000 LOG_STATS 0x0001 LOG_TOP 0x0002 LOG_THREADS 0x0004 LOG_SYSCALLS 0x0008 LOG_ASYNCH 0x0010 LOG_INTERP 0x0020 LOG_EMIT 0x0040 LOG_LINKS 0x0080 LOG_CACHE 0x0100 LOG_FRAGMENT 0x0200 LOG_DISPATCH 0x0400 LOG_MONITOR 0x0800 LOG_HEAP 0x1000 LOG_VMAREAS 0x2000 LOG_ALL 0x3fffIt is easiest to set the mask using the Windows GUI's dialog box for setting it. You can copy and paste the resulting mask value to set the mask outside of the GUI.
|
DynamoRIO currently comes with two profiling options. The first, selected with the -prof_pcs runtime option, is a simple statistical sampler. (This option is currently available only under Linux.) This option sets a timer to periodically interrupt DynamoRIO and query which part of DynamoRIO was running. When the program ends, a distribution of the samples is printed to the file ``pcsamples.TID''. (This option is currently available only under Linux.) You should expect to see the majority of the samples occurring in the fragment cache. The value of the pc each time the timer went off is also recorded, and these pc's (along with corresponding fragment tags and offsets) are also printed to the file ``pcsamples.TID''.
The other profiling option requires the use of the profile library. To use it, set the -prof_counts runtime option. This measures the execution count of each exit from each trace. Its overhead is noticeable. The exit counts are printed out with the traces in the file ``traces.TID'', so you must also select either -tracedump_text or -tracedump_binary.
|
An alternative to running an entire application under DynamoRIO is to use the application interface to specify a portion of the application to run. This interface consists of the following routines:
#include#include #include "dynamorio.h" main() { int rc = dynamorio_app_init(); assert(rc == 0); dynamorio_app_start(); printf("Hello world!\n"); dynamorio_app_stop(); dynamorio_app_exit(); }
You simply compile this application and link it with the DynamoRIO library corresponding to your current execution environment (Linux or Win32). On Linux, you must also link with the libc and libdl libraries. When you execute this application, you shouldn't notice any difference, except that it might run a bit slower. Since there is next to zero reuse in this simple application, running the application and its library routines in DynamoRIO's code cache will slow down the application. If you wrap dynamorio_app_start and dynamorio_app_stop around the frequently executed portions of your application (those with lots of reuse), you should observe very little overhead.
|