duran 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Eric Monti
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,11 @@
+= duran
+
+Duran is an attempt to embed ruby in the DynamoRIO dynamic binary translation 
+framework. Duran also provides FFI bindings for the DynamoRIO C library which
+can be used similarly to the C tool API.
+
+For DynamoRIO documentation and downloads, please see http://www.dynamorio.org
+
+== Copyright
+
+Copyright (c) 2010 Eric Monti. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "duran"
+    gem.summary = %Q{Embedded Ruby client and FFI bindings for the DyanoRIO library.}
+    gem.description = %Q{Embedded Ruby client and FFI bindings for the DyanoRIO dynamic binary translation library.}
+    gem.email = "esmonti@gmail.com"
+    gem.homepage = "http://github.com/emonti/duran"
+    gem.authors = ["Eric Monti"]
+    gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "duran #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/client_src/dr_include/dr_api.h

@@ -0,0 +1,102 @@
+/* **********************************************************
+ * Copyright (c) 2002-2008 VMware, Inc.  All rights reserved.
+ * **********************************************************/
+
+/*
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * * Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ * 
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ *   this list of conditions and the following disclaimer in the documentation
+ *   and/or other materials provided with the distribution.
+ * 
+ * * Neither the name of VMware, Inc. nor the names of its contributors may be
+ *   used to endorse or promote products derived from this software without
+ *   specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL VMWARE, INC. OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+ * DAMAGE.
+ */
+
+#ifndef _DR_API_H_
+#define _DR_API_H_ 1
+
+/**
+ * @file dr_api.h
+ * @brief Top-level include file for DynamoRIO API.  
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Defines and type definitions */
+#include "dr_defines.h"
+
+/* Event registration routines */
+#include "dr_events.h"
+
+/* Application start/stop interface */
+#include "dr_app.h"
+
+/* opnd_t (instruction operand) routines */
+#include "dr_ir_opnd.h"
+
+/* High-level routines: memory allocation, mutex support, file 
+ * support, printing, thread support, adaptive optimization, 
+ * custom traces, processor-specific utilities, trace dumping, 
+ * and module information.
+ */
+#include "dr_tools.h"
+
+/* Utility routines for identifying features of the processor. */
+#include "dr_proc.h"
+
+/* Instruction convenience & decode/disassemble routines */
+#include "dr_ir_utils.h"
+
+/* instrlist_t routines */
+#include "dr_ir_instrlist.h"
+
+/* instr_t routines */
+#include "dr_ir_instr.h"
+
+/* opcode OP_ constants and opcode-only routines */
+#include "dr_ir_opcodes.h"
+
+/* CREATE_INSTR_ macros */
+#include "dr_ir_macros.h"
+
+/**
+ * When registering a process, users must provide a list of paths to
+ * client libraries and their associated client-specific options.  DR
+ * looks up "dr_init" in each client library and calls that function
+ * when the process starts.  Clients can register to receive callbacks
+ * for the various events within dr_init.  Note that client paths and
+ * options cannot include semicolons. \p client_id is the ID supplied
+ * at registration and is used to identify the client for
+ * dr_get_options(), dr_get_client_path(), and external nudges.
+ */
+DR_EXPORT void dr_init(client_id_t client_id);
+
+/* Version checking */
+/* This equals major*100 + minor */
+DR_EXPORT LINK_ONCE int _USES_DR_VERSION_ = 105;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _DR_API_H_ */

data/client_src/dr_include/dr_app.h

@@ -0,0 +1,92 @@
+/* **********************************************************
+ * Copyright (c) 2002-2008 VMware, Inc.  All rights reserved.
+ * **********************************************************/
+
+/*
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * * Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ * 
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ *   this list of conditions and the following disclaimer in the documentation
+ *   and/or other materials provided with the distribution.
+ * 
+ * * Neither the name of VMware, Inc. nor the names of its contributors may be
+ *   used to endorse or promote products derived from this software without
+ *   specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL VMWARE, INC. OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+ * DAMAGE.
+ */
+
+/**
+ * @file dr_app.h
+ * @brief DR's application interface for running portions
+ * of a program under its control.
+ */
+
+#ifndef _DR_APP_H_
+#define _DR_APP_H_ 1
+
+#ifdef WINDOWS
+#  ifdef DR_APP_EXPORTS
+#    define DR_APP_API __declspec(dllexport)
+#  else
+#    define DR_APP_API __declspec(dllimport)
+#  endif
+#else /* LINUX */
+#  if defined(DR_APP_EXPORTS) && defined(USE_VISIBILITY_ATTRIBUTES)
+#    define DR_APP_API __attribute__ ((visibility ("default")))
+#  else
+#    define DR_APP_API
+#  endif
+#endif
+
+/****************************************************************************
+ * DR Application Interface
+ */
+
+/**
+ * Application-wide initialization. Must be called before any other
+ * API function, and before the application creates any threads. Returns
+ * zero on success.
+ */
+DR_APP_API int dr_app_setup(void);
+
+/**
+ * Application-wide cleanup.  Prints statistics. Returns zero on success.
+ */
+DR_APP_API int dr_app_cleanup(void);
+
+/**
+ * Causes application to run under DR control upon return 
+ * from this call.
+ */
+DR_APP_API void dr_app_start(void);
+
+/**
+ * Causes application to run directly on the machine upon return 
+ * from this call; no effect if application is not currently
+ * running under DR control.
+ */
+DR_APP_API void dr_app_stop(void);
+
+/**
+ * Causes application to run under DR control upon return from 
+ * this call.  DR never releases control. Useful for overriding 
+ * dr_app_start/dr_app_stop calls in the rest of a program.
+ */
+DR_APP_API void dr_app_take_over(void);
+
+#endif /* _DR_APP_H_ */

data/client_src/dr_include/dr_config.h

@@ -0,0 +1,650 @@
+/* **********************************************************
+ * Copyright (c) 2002-2009 VMware, Inc.  All rights reserved.
+ * **********************************************************/
+
+/*
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * * Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ * 
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ *   this list of conditions and the following disclaimer in the documentation
+ *   and/or other materials provided with the distribution.
+ * 
+ * * Neither the name of VMware, Inc. nor the names of its contributors may be
+ *   used to endorse or promote products derived from this software without
+ *   specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL VMWARE, INC. OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+ * DAMAGE.
+ */
+
+#ifndef _DR_CONFIG_H_
+#define _DR_CONFIG_H_ 1
+
+#ifdef WINDOWS
+/****************************************************************************
+ * Deployment API
+ */
+/**
+ * @file dr_config.h
+ * @brief Deployment API for Windows.  Use these functions to register
+ * processes to run under DynamoRIO, unregister processes, obtain existing 
+ * registration information, and nudge running processes.
+ * \note The dr_config library is currently not multi-thread safe. Users of
+ * the library should ensure that no more then one thread accesses the library
+ * at a time.  This limitation will be addressed in future releases.
+ */
+
+/** Maximum length of a registered process's options string */
+#define DR_MAX_OPTIONS_LENGTH 512
+
+/** Specifies DynamoRIO's operation mode. */
+typedef enum {
+
+    /** 
+     * No mode.  Clients should not attempt to register a process in
+     * this mode.
+     */
+    DR_MODE_NONE = 0,
+
+    /** Run DynamoRIO in Code Manipulation mode. */
+    DR_MODE_CODE_MANIPULATION = 1,
+
+
+
+} dr_operation_mode_t;
+
+/** Return status codes for process registration, unregistration and nudging. */
+typedef enum {
+    /** Operation succeeded. */
+    DR_SUCCESS,
+
+    /** Process registration failed due to an existing registration. */
+    DR_PROC_REG_EXISTS,
+
+    /** Operation failed because the supplied process is not registered. */
+    DR_PROC_REG_INVALID,
+
+    /** Client registration failed due to an invalid priority value. */
+    DR_PRIORITY_INVALID,
+
+    /** Client registration failed due to a conflicting ID. */
+    DR_ID_CONFLICTING,
+
+    /** Client operation failed due to an invalid client ID. */
+    DR_ID_INVALID,
+
+    /** Unknown failure. Check that caller has adequate permissions for this operation. */
+    DR_FAILURE,
+
+    /** Nudge operation failed because the specified process id is not under DR. */
+    DR_NUDGE_PID_NOT_INJECTED,
+
+    /** Nudge operation timed out waiting for target process to finish handling a nudge.*/
+    DR_NUDGE_TIMEOUT,
+
+} dr_config_status_t;
+
+/** Allow targeting both WOW64 and native 64-bit processes separately. */
+typedef enum {
+    DR_PLATFORM_DEFAULT, /**< The platform this tool is compiled for. */
+    DR_PLATFORM_32BIT,   /**< 32-bit settings (for 32-bit or WOW64 processes). */
+    DR_PLATFORM_64BIT,   /**< 64-bit settings (for native 64-bit processes). */
+} dr_platform_t;
+
+/**
+ * Register a process to run under DynamoRIO.  This requires administrative
+ * privileges.  Note that this routine only sets the base options to run
+ * a process under DynamoRIO.  To register one or more clients, call
+ * dr_register_client() subsequently.
+ *
+ * \param[in]   process_name    A NULL-terminated string specifying the name 
+ *                              of the target process.  The string should 
+ *                              identify the base name of the process, not the 
+ *                              full path of the executable (e.g., calc.exe).
+ *
+ * \param[in]   dr_root_dir     A NULL-terminated string specifying the full
+ *                              path to a valid DynamoRIO root directory.
+ *                              The string length cannot exceed MAX_PATH.
+ *
+ * \param[in]   dr_mode         Specifies the mode under which DynamoRIO should 
+ *                              operate.  See dr_operation_mode_t.
+ *
+ * \param[in]   debug           If true, a DynamoRIO debug build will be used;
+ *                              otherwise, a release build will be used.
+ *
+ * \param[in]   dr_platform     Configurations are kept separate on 64-bit Windows
+ *                              for 32-bit (WOW64) processes and 64-bit processes.
+ *                              This parameter allows selecting which of those
+ *                              configurations to set.
+ *
+ * \param[in]   dr_options      A NULL-terminated string controlling
+ *                              DynamoRIO's behavior.  Most users should
+ *                              not need to specify options.  The total
+ *                              string length cannot exceed #DR_MAX_OPTIONS_LENGTH.
+ *
+ * \return      A dr_config_status_t code indicating the result of 
+ *              registration.  Note that registration fails if the requested
+ *              process is already registered.  To modify a process's 
+ *              registration, first call dr_unregister_process() to remove an
+ *              existing registration.
+ *
+ * \remarks
+ * After registration, a process will run under DynamoRIO the next time
+ * it launches.  Note that some processes may require a system reboot to 
+ * restart.  Process registration persists across reboots until explicitly 
+ * unregistered.
+ *
+ * \note On Windows NT, a reboot is required after the initial
+ * dr_register_process() in order for DynamoRIO to take control of any
+ * application.
+ *
+ * \note An application that does not link with user32.dll will not be
+ * run under control of DynamoRIO unless it's launched by the \c drinject.exe 
+ * tool (in bin/bin32 or bin/bin64) or the parent process (typically
+ * explorer.exe, for manually launched applications) is already under
+ * DynamoRIO control (the parent can be in any mode, but 32-bit parent
+ * cannot inject into a 64-bit child). Only some small non-graphical
+ * applications do not link with user32.dll.
+ */
+dr_config_status_t 
+dr_register_process(const char *process_name,
+                    const char *dr_root_dir,
+                    dr_operation_mode_t dr_mode,
+                    bool debug,
+                    dr_platform_t dr_platform,
+                    const char *dr_options);
+
+/**
+ * Unregister a process from running under DynamoRIO.  This requires administrative
+ * privileges.
+ *
+ * \param[in]   process_name    A NULL-terminated string specifying the name 
+ *                              of the target process.  The string should 
+ *                              identify the base name of the process, not the 
+ *                              full path of the executable (e.g., calc.exe).
+ *
+ * \param[in]   dr_platform     Configurations are kept separate on 64-bit Windows
+ *                              for 32-bit (WOW64) processes and 64-bit processes.
+ *                              This parameter allows selecting which of those
+ *                              configurations to unset.
+ *
+ * \return      A dr_config_status_t code indicating the result of 
+ *              unregistration.  Note that unregistration fails if the process 
+ *              is not currently registered to run under DynamoRIO.
+ */
+dr_config_status_t
+dr_unregister_process(const char *process_name,
+                      dr_platform_t dr_platform);
+
+/**
+ * Check if a process is registered to run under DynamoRIO.  To obtain client
+ * information, use dr_get_client_info().
+ *
+ * \param[in]   process_name    A NULL-terminated string specifying the name 
+ *                              of the target process.  The string should 
+ *                              identify the base name of the process, not the 
+ *                              full path of the executable (e.g., calc.exe).
+ *
+ * \param[in]   dr_platform     Configurations are kept separate on 64-bit Windows
+ *                              for 32-bit (WOW64) processes and 64-bit processes.
+ *                              This parameter allows selecting which of those
+ *                              configurations to check.
+ *
+ * \param[out]  dr_root_dir     If the process is registered, the root DynamoRIO
+ *                              directory provided at registration.  Callers can
+ *                              pass NULL if this value is not needed.  Otherwise, 
+ *                              the parameter must be a caller-allocated array of 
+ *                              length MAX_PATH.
+ *
+ * \param[out]  dr_mode         If the process is registered, the mode provided
+ *                              at registration.  Callers can pass NULL if this
+ *                              value is not needed.
+ *
+ * \param[out]  debug           If the process is registered, the debug flag
+ *                              provided at registration.  Callers can pass NULL
+ *                              if this value is not needed.
+ *
+ * \param[out]  dr_options      If the process is registered, the extra DynamoRIO
+ *                              parameters provided at registration.  Callers can
+ *                              pass NULL if this value is not needed.  Otherwise,
+ *                              the parameter must be a caller-allocated array of
+ *                              length #DR_MAX_OPTIONS_LENGTH.
+ *
+ * \return      true if the process is registered for the given platform.
+ */
+bool
+dr_process_is_registered(const char *process_name,
+                         dr_platform_t dr_platform,
+                         char *dr_root_dir              /* OUT */,
+                         dr_operation_mode_t *dr_mode   /* OUT */,
+                         bool *debug                    /* OUT */,
+                         char *dr_options               /* OUT */);
+
+typedef struct _dr_registered_process_iterator_t dr_registered_process_iterator_t;
+
+/**
+ * Creates and starts an iterator for iterating over all processes registered for
+ * the given platform. 
+ *
+ * \param[in]   dr_platform     Configurations are kept separate on 64-bit Windows
+ *                              for 32-bit (WOW64) processes and 64-bit processes.
+ *                              This parameter allows selecting which of those
+ *                              configurations to check.
+ *
+ * \return      iterator for use with dr_registered_process_iterator_hasnext()and 
+ *              dr_registered_process_iterator_next().  Must be freed
+ *              with dr_registered_process_iterator_stop()
+ */
+dr_registered_process_iterator_t *
+dr_registered_process_iterator_start(dr_platform_t dr_platform);
+
+/**
+ * \param[in]    iter           A registered process iterator created with
+ *                              dr_registered_process_iterator_start()
+ *
+ * \return      true if there are more registered processes to iterate over
+ */
+bool
+dr_registered_process_iterator_hasnext(dr_registered_process_iterator_t *iter);
+
+/**
+ * Return information about a registered process
+ *
+ * \param[in]    iter           A registered process iterator created with
+ *                              dr_registered_process_iterator_start().
+ *
+ * \param[out]   process_name   The name of the registered process. Callers can
+ *                              pass NULL if this value is not needed. Otherwise
+ *                              the parameter must be a caller-allocated array
+ *                              of length MAX_PATH.
+ *
+ * \param[out]  dr_root_dir     The root DynamoRIO directory provided at registration.
+ *                              Callers can pass NULL if this value is not needed.
+ *                              Otherwise, the parameter must be a caller-allocated
+ *                              array of length MAX_PATH.
+ *
+ * \param[out]  dr_mode         If the process is registered, the mode provided
+ *                              at registration.  Callers can pass NULL if this
+ *                              value is not needed.
+ *
+ * \param[out]  debug           If the process is registered, the debug flag
+ *                              provided at registration.  Callers can pass NULL
+ *                              if this value is not needed.
+ *
+ * \param[out]  dr_options      If the process is registered, the extra DynamoRIO
+ *                              parameters provided at registration.  Callers can
+ *                              pass NULL if this value is not needed.  Otherwise,
+ *                              the parameter must be a caller-allocated array of
+ *                              length #DR_MAX_OPTIONS_LENGTH.
+ *
+ * \return      true if the process is registered for the given platform.
+ */
+void
+dr_registered_process_iterator_next(dr_registered_process_iterator_t *iter,
+                                    char *process_name /* OUT */,
+                                    char *dr_root_dir /* OUT */,
+                                    dr_operation_mode_t *dr_mode /* OUT */,
+                                    bool *debug /* OUT */,
+                                    char *dr_options /* OUT */);
+
+/**
+ * Stops and frees a registered process iterator.
+ *
+ * \param[in]    iter           A registered process iterator created with
+ *                              dr_registered_process_iterator_start()
+ */
+void
+dr_registered_process_iterator_stop(dr_registered_process_iterator_t *iter);
+
+/**
+ * Register a client for a particular process.  Note that the process must
+ * first be registered via dr_register_process() before calling this routine.
+ *
+ * \param[in]   process_name    A NULL-terminated string specifying the name 
+ *                              of the target process.  The string should 
+ *                              identify the base name of the process, not the 
+ *                              full path of the executable (e.g., calc.exe).
+ *
+ * \param[in]   dr_platform     Configurations are kept separate on 64-bit Windows
+ *                              for 32-bit (WOW64) processes and 64-bit processes.
+ *                              This parameter allows selecting which of those
+ *                              configurations to unset.
+ *
+ * \param[in]   client_id       A client_id_t uniquely identifying the client.
+ *                              DynamoRIO provides the client ID as a parameter
+ *                              to dr_init().  Clients use this ID to retrieve
+ *                              client-specific path and option information.
+ *                              Outside entities also identify the target of
+ *                              a nudge via this ID.
+ *
+ * \param[in]   client_pri      The client number, or priority.  Client registration
+ *                              includes a value indicating the priority of a client
+ *                              relative to other clients.  In multi-client settings,
+ *                              a client's priority influences event callback 
+ *                              ordering.  That is, higher priority clients can 
+ *                              register their callbacks first; DynamoRIO then calls
+ *                              these routines last.  Client priorities range
+ *                              consecutively from 0 to N-1, where N is the number
+ *                              of registered clients.  Specify priority
+ *                              0 to register a client with highest priority.
+ *
+ * \param[in]   client_path     A NULL-terminated string specifying the full path
+ *                              to a valid client library.  The string length
+ *                              cannot exceed MAX_PATH.  The client path may not
+ *                              include any semicolons.
+ *
+ * \param[in]   client_options  A NULL-terminated string specifying options that
+ *                              are available to the client via dr_get_options().
+ *                              The string length cannot exceed #DR_MAX_OPTIONS_LENGTH.
+ *                              The client options may not include any semicolons.
+ *
+ * \return      A dr_config_status_t code indicating the result of registration.
+ */
+dr_config_status_t
+dr_register_client(const char *process_name,
+                   dr_platform_t dr_platform,
+                   client_id_t client_id,
+                   size_t client_pri,
+                   const char *client_path,
+                   const char *client_options);
+
+/**
+ * \param[in]   process_name    A NULL-terminated string specifying the name 
+ *                              of the target process.  The string should 
+ *                              identify the base name of the process, not the 
+ *                              full path of the executable (e.g., calc.exe).
+ *
+ * \param[in]   dr_platform     Configurations are kept separate on 64-bit Windows
+ *                              for 32-bit (WOW64) processes and 64-bit processes.
+ *                              This parameter allows selecting which of those
+ *                              configurations to unset.
+ *
+ * \param[in]   client_id       The unique client ID provided at client
+ *                              registration.
+ *
+ * \return      A dr_config_status_t code indicating the result of unregistration.
+ */
+dr_config_status_t
+dr_unregister_client(const char *process_name,
+                     dr_platform_t dr_platform,
+                     client_id_t client_id);
+
+/**
+ * Retrieve the number of clients registered for a particular process.
+ *
+ * \param[in]   process_name    A NULL-terminated string specifying the name 
+ *                              of the target process.  The string should 
+ *                              identify the base name of the process, not the 
+ *                              full path of the executable (e.g., calc.exe).
+ *
+ * \param[in]   dr_platform     Configurations are kept separate on 64-bit Windows
+ *                              for 32-bit (WOW64) processes and 64-bit processes.
+ *                              This parameter allows selecting which of those
+ *                              configurations to unset.
+ *
+ * \return      The number of clients registered for the given process and platform.
+ */
+size_t
+dr_num_registered_clients(const char *process_name,
+                          dr_platform_t dr_platform);
+
+/**
+ * Retrieve client registration information for a particular process.
+ *
+ * \param[in]   process_name    A NULL-terminated string specifying the name 
+ *                              of the target process.  The string should 
+ *                              identify the base name of the process, not the 
+ *                              full path of the executable (e.g., calc.exe).
+ *
+ * \param[in]   dr_platform     Configurations are kept separate on 64-bit Windows
+ *                              for 32-bit (WOW64) processes and 64-bit processes.
+ *                              This parameter allows selecting which of those
+ *                              configurations to unset.
+ *
+ * \param[in]   client_id       The unique client ID provided at client
+ *                              registration.
+ *
+ * \param[out]  client_pri      The client's priority.
+ *
+ * \param[out]  client_path     The client's path provided at registration.
+ *                              Callers can pass NULL if this value is not needed.
+ *                              Otherwise, the parameter must be a caller-allocated
+ *                              array of length MAX_PATH.
+ *
+ * \param[out]  client_options  The client options provided at registration.
+ *                              Callers can pass NULL if this value is not needed.
+ *                              Otherwise, the parameter must be a caller-allocated
+ *                              array of length #DR_MAX_OPTIONS_LENGTH.
+ *
+ * \return      A dr_config_status_t code indicating the result of the call.
+ */
+dr_config_status_t
+dr_get_client_info(const char *process_name,
+                   dr_platform_t dr_platform,
+                   client_id_t client_id,
+                   size_t *client_pri,  /* OUT */
+                   char *client_path,   /* OUT */
+                   char *client_options /* OUT */);
+
+typedef struct _dr_client_iterator_t dr_client_iterator_t;
+
+/**
+ * Creates and starts an iterator for iterating over all clients registered for
+ * the given process.
+ *
+ * \param[in]   process_name    A NULL-terminated string specifying the name 
+ *                              of the target process.  The string should 
+ *                              identify the base name of the process, not the 
+ *                              full path of the executable (e.g., calc.exe).
+ *
+ * \param[in]   dr_platform     Configurations are kept separate on 64-bit Windows
+ *                              for 32-bit (WOW64) processes and 64-bit processes.
+ *                              This parameter allows selecting which of those
+ *                              configurations to check.
+ *
+ * \return      iterator for use with dr_client_iterator_hasnext() and
+ *              dr_client_iterator_next().  Must be freed with
+ *              dr_client_iterator_stop()
+ */
+dr_client_iterator_t *
+dr_client_iterator_start(const char *process_name,
+                         dr_platform_t dr_platform);
+
+/**
+ * \param[in]   iter            A client iterator created with dr_client_iterator_start()
+ *
+ * \return      true if there are more clients to iterate over
+ */
+bool
+dr_client_iterator_hasnext(dr_client_iterator_t *iter);
+
+/**
+ * Return information about a client.
+ *
+ * \param[in]   iter            A client iterator created with dr_client_iterator_start()
+ *
+ * \param[out]  client_id       The unique client ID provided at client registration.
+ *
+ * \param[out]  client_pri      The client's priority.
+ *
+ * \param[out]  client_path     The client's path provided at registration.
+ *                              Callers can pass NULL if this value is not needed.
+ *                              Otherwise, the parameter must be a caller-allocated
+ *                              array of length MAX_PATH.
+ *
+ * \param[out]  client_options  The client options provided at registration.
+ *                              Callers can pass NULL if this value is not needed.
+ *                              Otherwise, the parameter must be a caller-allocated
+ *                              array of length #DR_MAX_OPTIONS_LENGTH.
+ */
+void
+dr_client_iterator_next(dr_client_iterator_t *iter,
+                        client_id_t *client_id, /* OUT */
+                        size_t *client_pri,     /* OUT */
+                        char *client_path,      /* OUT */
+                        char *client_options    /* OUT */);
+
+/**
+ * Stops and frees a client iterator.
+ *
+ * \param[in]   iter            A client iterator created with dr_client_iterator_start()
+ */
+void
+dr_client_iterator_stop(dr_client_iterator_t *iter);
+
+
+/**
+ * Provides a mechanism for an external entity on the guest OS to
+ * communicate with a client.  Requires administrative privileges.  A
+ * process 'nudge' causes a client event handler to be invoked (use
+ * dr_register_nudge_event() to register the handler function).  A
+ * nudge is ignored if the process is not running under DynamoRIO,
+ * the specified client is not loaded, or if the client does not 
+ * provide a handler.
+ *
+ * \param[in]   process_name    A NULL-terminated string specifying the name 
+ *                              of the target process.  The string should 
+ *                              identify the base name of the process, not the 
+ *                              full path of the executable.
+ *
+ * \param[in]   client_id       The unique client ID provided at client
+ *                              registration.
+ *
+ * \param[in]   arg             An argument passed to the client's nudge
+ *                              handler.
+ *
+ * \param[in]   timeout_ms      The number of milliseconds to wait for each
+ *                              nudge to complete before continuing. If INFINITE
+ *                              is supplied then the wait is unbounded. If 0
+ *                              is supplied the no wait is performed.  If a
+ *                              wait times out DR_NUDGE_TIMEOUT will be returned.
+ *
+ * \param[out]  nudge_count     Returns the number of processes nudged.
+ *                              Client can supply NULL if this value is
+ *                              not needed.
+ *
+ * \return      A dr_config_status_t code indicating the result of the nudge.
+ *
+ * \remarks
+ * If there are multiple processes executing with the same name, all
+ * of them are nudged.
+ *
+ * \remarks
+ * A process nudge is a one way asynchronous communication from an
+ * external entity to a client.  It does not allow a client to
+ * return information back to the nudge originator.  To communicate
+ * from a client to another process, use the channels specified
+ * in \ref sec_comm.
+ *
+ * \note Nudging 64-bit processes is not yet supported.
+ */
+dr_config_status_t
+dr_nudge_process(const char *process_name,
+                 client_id_t client_id,
+                 uint64 arg,
+                 uint timeout_ms,
+                 int *nudge_count /*OUT */);
+
+/**
+ * Provides a mechanism for an external entity on the guest OS to
+ * communicate with a client.  Requires administrative privileges.  A
+ * process 'nudge' causes a client event handler to be invoked (use
+ * dr_register_nudge_event() to register the handler function).  A
+ * nudge is ignored if the process is not running under DynamoRIO,
+ * the specified client is not loaded, or if the client does not 
+ * provide a handler.
+ *
+ * \param[in]   process_id      The system id of the process to nudge
+ *                              (see dr_get_process_id())
+ *
+ * \param[in]   client_id       The unique client ID provided at client
+ *                              registration.
+ *
+ * \param[in]   arg             An argument passed to the client's nudge
+ *                              handler.
+ *
+ * \param[in]   timeout_ms      The number of milliseconds to wait for the
+ *                              nudge to complete before returning. If INFINITE
+ *                              is supplied then the wait is unbounded. If 0
+ *                              is supplied the no wait is performed.  If the
+ *                              wait times out DR_NUDGE_TIMEOUT will be returned.
+ *
+ * \return      A dr_config_status_t code indicating the result of the nudge.
+ *
+ * \remarks
+ * A process nudge is a one way asynchronous communication from an
+ * external entity to a client.  It does not allow a client to
+ * return information back to the nudge originator.  To communicate
+ * from a client to another process, use the channels specified
+ * in \ref sec_comm.
+ *
+ * \note Nudging 64-bit processes is not yet supported.
+ */
+dr_config_status_t
+dr_nudge_pid(process_id_t process_id,
+             client_id_t client_id,
+             uint64 arg,
+             uint timeout_ms);
+
+/**
+ * Provides a mechanism for an external entity on the guest OS to
+ * communicate with a client.  Requires administrative privileges.  A
+ * process 'nudge' causes a client event handler to be invoked (use
+ * dr_register_nudge_event() to register the handler function).  A
+ * nudge is ignored if the process is not running under DynamoRIO,
+ * the specified client is not loaded, or if the client does not 
+ * provide a handler.  Nudges are attempted to all processes running
+ * on the system.
+ *
+ * \param[in]   client_id       The unique client ID provided at client
+ *                              registration.
+ *
+ * \param[in]   arg             An argument passed to the client's nudge
+ *                              handler.
+ *
+ * \param[in]   timeout_ms      The number of milliseconds to wait for each
+ *                              nudge to complete before continuing. If INFINITE
+ *                              is supplied then the wait is unbounded. If 0
+ *                              is supplied the no wait is performed.  If a
+ *                              wait times out DR_NUDGE_TIMEOUT will be returned.
+ *
+ * \param[out]  nudge_count     Returns the number of processes nudged.
+ *                              Client can supply NULL if this value is
+ *                              not needed.
+ *
+ * \return      A dr_config_status_t code indicating the result of the nudge.
+ *
+ * \remarks
+ * A process nudge is a one way asynchronous communication from an
+ * external entity to a client.  It does not allow a client to
+ * return information back to the nudge originator.  To communicate
+ * from a client to another process, use the channels specified
+ * in \ref sec_comm.
+ *
+ * \note Nudging 64-bit processes is not yet supported.
+ */
+dr_config_status_t
+dr_nudge_all(client_id_t client_id,
+             uint64 arg,
+             uint timeout_ms,
+             int *nudge_count /*OUT */);
+
+#endif /* WINDOWS */
+
+
+
+
+#endif /* _DR_CONFIG_H_ */