i#147: Alternate-bitwidth client support

Adds new options and interfaces to specify alternate-bitwidth client
libraries for use when the application creates a child process of the
other bitwidth.

For DR, adds -client_lib32 and -client_lib64 options.  Switches main
usage to use the appropriate option, with its contents then copied
into -client_lib (to avoid the pain of removing that options).

For drconfiglib, adds dr_register_client_ex() with
dr_client_iterator_next_ex() to support querying other-bitwidth client
registrations.

Adds a new libutil.drconfig_test for drconfiglib.  Fixes a bug found
by the test: existing client queries were cutting off the last
character of the path and options.

For drrun and drconfig, adds "-c32" and "-c64" options, with an
additional "--" separating the client options between them.

For tool files, adds CLIENT{32,64}_{REL,ABS}.  Updates drcov,
drcpusim, and drcachesim to use the new syntax and drcachesim's
launcher to process it.  Tested these manually:
    ===========================================================================
    $ ninja install
    $ rm *.log
    $ ../exports/bin64/drrun -t drcov -- ~/dr/test/execve64 ~/dr/test/hello32
    $ l -t *.log
    20K drcov.execve64.109583.0000.proc.log  20K drcov.execve64.109585.0000.proc.log
    20K drcov.hello32.109585.0000.proc.log
    $ rm -rf drm*.dir
    $ ../exports/bin64/drrun -verbose -t drcachesim -verbose 1 -offline -- ~/dr/test/execve64 ~/dr/test/hello32
    $ l -td *.dir
    4.0K drmemtrace.hello32.117714.7095.dir/  4.0K drmemtrace.execve64.117714.6260.dir/
    4.0K drmemtrace.execve64.117713.9314.dir/
    ===========================================================================

Adds tests of -c32/-c64 to the existing cross-arch linux.execve{32,64}
tests (Windows won't work until #803 is addressed).
The tests look like this:
    ===========================================================================
    $ cmake . && ctest -V -R 'linux.execve(32|64)'

    8: Running test command: "/home/bruening/dr/git/build_x64_dbg_tests/bin64/drrun" "-32" "-dr_home" "/home/bruening/dr/git/build_x64_dbg_tests/suite/tests/32bit" "-stderr_mask" "0xC" "-dumpcore_mask" "0" "-c32" "/home/bruening/dr/git/build_x64_dbg_tests/suite/tests/32bit/suite/tests/bin/libclient.large_options.dll.so" "-paramA" "foo" "-paramB" "bar" "--" "-c64" "/home/bruening/dr/git/build_x64_dbg_tests/suite/tests/bin/libclient.large_options.dll.so" "-paramA" "foo" "-paramB" "bar" "--" "/home/bruening/dr/git/build_x64_dbg_tests/suite/tests/32bit/suite/tests/bin/linux.execve32" "/home/bruening/dr/git/build_x64_dbg_tests/suite/tests/bin/linux.execve-sub64"
    8: large_options passed: -paramA foo -paramB bar
    8: parent is running under DynamoRIO
    8: parent waiting for child
    8: child is running under DynamoRIO
    8: large_options passed: -paramA foo -paramB bar
    8: it_worked
    8: running under DynamoRIO
    8: large_options exiting
    8: child has exited
    8: large_options exiting
    8:
    1/2 Test #8: linux.execve32 ...................   Passed    3.93 sec

    9: Test command: /home/bruening/dr/git/build_x64_dbg_tests/bin64/drrun "-stderr_mask" "0xC" "-dumpcore_mask" "0" "-c32" "/home/bruening/dr/git/build_x64_dbg_tests/suite/tests/32bit/suite/tests/bin/libclient.large_options.dll.so" "-paramA" "foo" "-paramB" "bar" "--" "-c64" "/home/bruening/dr/git/build_x64_dbg_tests/suite/tests/bin/libclient.large_options.dll.so" "-paramA" "foo" "-paramB" "bar" "--" "/home/bruening/dr/git/build_x64_dbg_tests/suite/tests/bin/linux.execve64" "/home/bruening/dr/git/build_x64_dbg_tests/suite/tests/32bit/suite/tests/bin/linux.execve-sub32"
    9: Test timeout computed to be: 1500
    9: large_options passed: -paramA foo -paramB bar
    9: parent is running under DynamoRIO
    9: parent waiting for child
    9: child is running under DynamoRIO
    9: large_options passed: -paramA foo -paramB bar
    9: it_worked
    9: running under DynamoRIO
    9: large_options exiting
    9: child has exited
    9: large_options exiting
    2/2 Test #9: linux.execve64 ...................   Passed    0.86 sec
    ===========================================================================

Issue: #147, #803
Fixes: #147

api/docs/intro.dox

@@ -387,6 +387,13 @@ of time for the child application.  To instead only
 follow children that are configured (via \c drconfig.exe), use the
 \ref op_children "-no_follow_children" runtime option.
 
+To ensure a client is loaded into a child process of a different
+bitwidth (i.e., a 32-bit child created by a 64-bit parent), use the \c
+-c32 and \c -c64 options to \c drconfig or \c drrun, with \c -- ending
+the first client's options:
+
+bin32/drrun.exe -c32 samples/bin32/bbsize.dll -- -c64 samples/bin64/bbsize.dll -- notepad
+
 To \ref sec_comm "nudge" all instances of \c notepad.exe running under
 DynamoRIO with argument "5", use:
 \code
@@ -594,6 +601,13 @@ Client options are not allowed to contain semicolons.  Additionally, the
 client option string combined with the path to the client library cannot
 contain all three quote characters (', ", `) simultaneously.
 
+To ensure a client is loaded into a child process of a different
+bitwidth (i.e., a 32-bit child created by a 64-bit parent), use the \c
+-c32 and \c -c64 options to \c drconfig or \c drrun, with \c -- ending
+the first client's options:
+
+bin32/drrun -c32 samples/bin32/bbsize.dll -- -c64 samples/bin64/bbsize.dll -- notepad
+
 \section multi_client Multiple Clients
 
 DynamoRIO does support multiple clients.  It is each client's
@@ -626,19 +640,26 @@ option.  To use the option, first create a file in the \p tools
 subdirectory of the root of the DynamoRIO installation called \p
 toolname.drrun32 or \p toolname.drrun64, depending on the target
 architecture.  Here, \p toolname is the desired external name of the tool.
-This file should contain one of the following lines:
+This file should contain one of the following lines, or two if
+they are a pair of CLIENT32_* and CLIENT64_* specifiers:
 
 \code
 CLIENT_ABS=/absolute/path/to/client
+CLIENT32_ABS=/absolute/path/to/32-bit-client
+CLIENT64_ABS=/absolute/path/to/64-bit-client
 \endcode
 
 or
 
 \code
 CLIENT_REL=relative/path/to/client/from/DynamoRIO/root
+CLIENT32_REL=relative/path/to/32-bit-client/from/DynamoRIO/root
+CLIENT64_REL=relative/path/to/64-bit-client/from/DynamoRIO/root
 \endcode
 
-This enables \p drrun to locate the tool's client library.
+This enables \p drrun to locate the tool's client library.  The 32 and
+64 specifiers allow pointing at alternate-bitwidth paths for use if
+the target application creates a child process of a different bitwidth.
 
 The file can also modify the default DynamoRIO runtime options (see \ref
 sec_options) via \p DR_OP= lines.  Each line contains only one option string
@@ -698,8 +719,8 @@ FRONTEND_REL=relative/path/to/front-end/from/DynamoRIO/root
 \endcode
 
 This will cause \p drrun to transfer control to the specified front-end
-executable, passing any tool arguments (including a client path, if \p
-CLIENT_ABS or \p CLIENT_REL appears after the \p FRONTEND_* command)
+executable, passing any tool arguments (including client paths, if \p
+CLIENT{,32,64}_{ABS,REL} appears after the \p FRONTEND_* command)
 followed by "--" and the target application command line.
 
 The path to the DynamoRIO install base can be included in the front-end

api/docs/release.dox

@@ -141,7 +141,10 @@ changes:
 The changes between version \DR_VERSION and 8.0.0 include the following minor
 compatibility changes:
 
- Nothing yet.
+ - drconfiglib (and thus drrun and drconfig) now sets only the new client path
+   options added to support other-bitwidth child processes.  This means that a
+   drconfiglib from this version will not properly configure for a DynamoRIO
+   core library from a prior version.
 
 Further non-compatibility-affecting changes include:
 
@@ -155,6 +158,12 @@ Further non-compatibility-affecting changes include:
    Not all API routines support the setting of error codes. Please look at their
    documentation to check if they do.
  - Added -instr_only_trace option to drcachesim.
+ - Added other-bitwidth child process support, with the other client library
+   specified by "-c32" "-c64" to drrun or drdeploy, by dr_register_client_ex()
+   with #dr_config_client_t.is_alt_bitwidth=true to drconfiglib, and by
+   CLIENT{32,64}_{ABS,REL} in tool files.
+   Added dr_get_client_info_ex() and dr_client_iterator_next_ex() to support
+   querying other-bitwidth client registration.
 
 **************************************************
 <hr>

clients/drcachesim/CMakeLists.txt

@@ -414,6 +414,17 @@ install_target(drraw2trace ${INSTALL_CLIENTS_BIN})
 set(INSTALL_DRCACHESIM_CONFIG ${INSTALL_CLIENTS_BASE})
 
 function (write_config_file dst bindir libdir)
+  # We include the alternate-bitwidth path, though it won't be there for
+  # a single build dir and such a child will have a fatal error.
+  if (X64)
+    string(REPLACE "lib64" "lib32" alt_libdir ${libdir})
+    set(CUR_BIT "64")
+    set(ALT_BIT "32")
+  else ()
+    set(CUR_BIT "32")
+    set(ALT_BIT "64")
+    string(REPLACE "lib64" "lib32" alt_libdir ${libdir})
+  endif ()
   if (DEBUG)
     set(debugopt "TOOL_OP=-dr_debug")
   else ()
@@ -426,8 +437,10 @@ TOOL_OP=-dr\n\
 TOOL_OP_DR_PATH\n\
 TOOL_OP_DR_BUNDLE=-dr_ops\n\
 TOOL_OP=-tracer\n\
-CLIENT_REL=${libdir}/${LIB_PFX}drmemtrace${LIB_EXT}\n\
-${debugopt}")
+CLIENT${CUR_BIT}_REL=${libdir}/${LIB_PFX}drmemtrace${LIB_EXT}\n\
+TOOL_OP=-tracer_alt\n\
+CLIENT${ALT_BIT}_REL=${alt_libdir}/${LIB_PFX}drmemtrace${LIB_EXT}\n\
+${debugopt}\n")
 endfunction ()
 
 if (X64)

clients/drcachesim/common/options.cpp

@@ -335,6 +335,12 @@ droption_t<std::string> op_tracer(DROPTION_SCOPE_FRONTEND, "tracer", "",
                                   "Path to the tracer",
                                   "The full path to the tracer library.");
 
+droption_t<std::string> op_tracer_alt(DROPTION_SCOPE_FRONTEND, "tracer_alt", "",
+                                      "Path to the alternate-bitwidth tracer",
+                                      "The full path to the tracer library for the other "
+                                      "bitwidth, for use on child processes with a "
+                                      "different bitwidth from their parent.");
+
 droption_t<std::string> op_tracer_ops(
     DROPTION_SCOPE_FRONTEND, "tracer_ops",
     DROPTION_FLAG_SWEEP | DROPTION_FLAG_ACCUMULATE | DROPTION_FLAG_INTERNAL, "",

clients/drcachesim/common/options.h

@@ -110,6 +110,7 @@ extern droption_t<std::string> op_dr_root;
 extern droption_t<bool> op_dr_debug;
 extern droption_t<std::string> op_dr_ops;
 extern droption_t<std::string> op_tracer;
+extern droption_t<std::string> op_tracer_alt;
 extern droption_t<std::string> op_tracer_ops;
 extern droption_t<bytesize_t> op_skip_refs;
 extern droption_t<bytesize_t> op_warmup_refs;

clients/drcachesim/launcher.cpp

@@ -167,6 +167,26 @@ configure_application(char *app_name, char **app_argv, std::string tracer_ops,
                            tracer_ops.c_str()) != DR_SUCCESS) {
         FATAL_ERROR("failed to register DynamoRIO client configuration");
     }
+    if (!op_tracer_alt.get_value().empty()) {
+        dr_config_client_t info;
+        info.struct_size = sizeof(info);
+        info.id = CLIENT_ID;
+        info.priority = 1;
+        char local_path[MAXIMUM_PATH];
+        dr_snprintf(local_path, BUFFER_SIZE_ELEMENTS(local_path), "%s",
+                    op_tracer_alt.get_value().c_str());
+        info.path = (char *)local_path;
+        char local_ops[MAXIMUM_PATH];
+        dr_snprintf(local_ops, BUFFER_SIZE_ELEMENTS(local_path), "%s",
+                    op_tracer_ops.get_value().c_str());
+        info.options = (char *)local_ops;
+        info.is_alt_bitwidth = true;
+        NOTIFY(1, "INFO", "configuring alt-bitwidth client \"%s\"",
+               op_tracer_alt.get_value().c_str());
+        if (dr_register_client_ex(process, pid, false /*local*/, DR_PLATFORM_DEFAULT,
+                                  &info) != DR_SUCCESS)
+            FATAL_ERROR("failed to register DynamoRIO client configuration");
+    }
     return true;
 }
 
@@ -269,6 +289,10 @@ _tmain(int argc, const TCHAR *targv[])
         if (!file_is_readable(op_tracer.get_value().c_str())) {
             FATAL_ERROR("tracer library %s is unreadable", op_tracer.get_value().c_str());
         }
+        // We deliberately do *not* check -tracer_alt, since we're guessing that
+        // path is available and it won't be for a single build dir.
+        // An other-bitwidth child will exit with a fatal error if the lib
+        // is not there and the user runs such an app.
         if (!file_is_readable(op_dr_root.get_value().c_str())) {
             FATAL_ERROR("invalid -dr_root %s", op_dr_root.get_value().c_str());
         }

clients/drcov/CMakeLists.txt

@@ -125,11 +125,23 @@ else (X64)
 endif (X64)
 
 function (write_config_file dst libdir)
+  # We include the alternate-bitwidth path, though it won't be there for
+  # a single build dir and such a child will have a fatal error.
+  if (X64)
+    string(REPLACE "lib64" "lib32" alt_libdir ${libdir})
+    set(CUR_BIT "64")
+    set(ALT_BIT "32")
+  else ()
+    set(CUR_BIT "32")
+    set(ALT_BIT "64")
+    string(REPLACE "lib64" "lib32" alt_libdir ${libdir})
+  endif ()
   file(WRITE  ${dst} "# drcov tool config file\n")
   file(APPEND ${dst} "# DynamoRIO options\n")
   file(APPEND ${dst} "DR_OP=-nop_initial_bblock\n")
   file(APPEND ${dst} "# client tool path\n")
-  file(APPEND ${dst} "CLIENT_REL=${libdir}/${LIB_PFX}drcov${LIB_EXT}\n")
+  file(APPEND ${dst} "CLIENT${CUR_BIT}_REL=${libdir}/${LIB_PFX}drcov${LIB_EXT}\n")
+  file(APPEND ${dst} "CLIENT${ALT_BIT}_REL=${alt_libdir}/${LIB_PFX}drcov${LIB_EXT}\n")
   file(APPEND ${dst} "# client tool options\n")
   file(APPEND ${dst} "TOOL_OP=\n")
 endfunction ()

clients/drcpusim/CMakeLists.txt

@@ -60,8 +60,20 @@ install_target(drcpusim ${INSTALL_CLIENTS_LIB})
 set(INSTALL_DRCPUSIM_CONFIG ${INSTALL_CLIENTS_BASE})
 
 function (write_config_file dst bindir libdir)
+  # We include the alternate-bitwidth path, though it won't be there for
+  # a single build dir and such a child will have a fatal error.
+  if (X64)
+    string(REPLACE "lib64" "lib32" alt_libdir ${libdir})
+    set(CUR_BIT "64")
+    set(ALT_BIT "32")
+  else ()
+    set(CUR_BIT "32")
+    set(ALT_BIT "64")
+    string(REPLACE "lib64" "lib32" alt_libdir ${libdir})
+  endif ()
   file(WRITE  ${dst} "# drcpusim tool config file\n")
-  file(APPEND ${dst} "CLIENT_REL=${libdir}/${LIB_PFX}drcpusim${LIB_EXT}\n")
+  file(APPEND ${dst} "CLIENT${CUR_BIT}_REL=${libdir}/${LIB_PFX}drcpusim${LIB_EXT}\n")
+  file(APPEND ${dst} "CLIENT${ALT_BIT}_REL=${alt_libdir}/${LIB_PFX}drcpusim${LIB_EXT}\n")
 endfunction ()
 
 if (X64)