include/pub_tool_redir.h

   1
   2 /*--------------------------------------------------------------------*/
   3 /*--- Redirections, etc.                          pub_tool_redir.h ---*/
   4 /*--------------------------------------------------------------------*/
   5
   6 /*
   7    This file is part of Valgrind, a dynamic binary instrumentation
   8    framework.
   9
  10    Copyright (C) 2000-2013 Julian Seward
  11       jseward@acm.org
  12
  13    This program is free software; you can redistribute it and/or
  14    modify it under the terms of the GNU General Public License as
  15    published by the Free Software Foundation; either version 2 of the
  16    License, or (at your option) any later version.
  17
  18    This program is distributed in the hope that it will be useful, but
  19    WITHOUT ANY WARRANTY; without even the implied warranty of
  20    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21    General Public License for more details.
  22
  23    You should have received a copy of the GNU General Public License
  24    along with this program; if not, write to the Free Software
  25    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  26    02111-1307, USA.
  27
  28    The GNU General Public License is contained in the file COPYING.
  29 */
  30
  31 #ifndef __PUB_TOOL_REDIR_H
  32 #define __PUB_TOOL_REDIR_H
  33
  34 #include "config.h"           /* DARWIN_VERS */
  35
  36 /* The following macros facilitate function replacement and wrapping.
  37
  38    Function wrapping and function replacement are similar but not
  39    identical.
  40
  41    A replacement for some function F simply diverts all calls to F
  42    to the stated replacement.  There is no way to get back to F itself
  43    from the replacement.
  44
  45    A wrapper for a function F causes all calls to F to instead go to
  46    the wrapper.  However, from inside the wrapper, it is possible
  47    (with some difficulty) to get to F itself.
  48
  49    You may notice that replacement is a special case of wrapping, in
  50    which the call to the original is omitted.  For implementation
  51    reasons, though, it is important to use the following macros
  52    correctly: in particular, if you want to write a replacement, make
  53    sure you use the VG_REPLACE_FN_ macros and not the VG_WRAP_FN_
  54    macros.
  55
  56    Finally there is the concept of prioritised behavioural equivalence
  57    tags.  A tag is a 5-digit decimal number (00000 to 99999) encoded
  58    in the name.  The top 4 digits are the equivalence class number,
  59    and the last digit is a priority.
  60
  61    When processing redirections at library load time, if the set of
  62    available specifications yields more than one replacement or
  63    wrapper function for a given address, the system will try to
  64    resolve the situation by examining the tags on the
  65    replacements/wrappers.
  66
  67    If two replacement/wrapper functions have the same tag and
  68    priority, then the redirection machinery will assume they have
  69    identical behaviour and can choose between them arbitrarily.  If
  70    they have the same tag but different priorities, then the one with
  71    higher priority will be chosen.  If neither case holds, then the
  72    redirection is ambiguous and the system will ignore one of them
  73    arbitrarily, but print a warning when running at -v or above.
  74
  75    The tag is mandatory and must comprise 5 decimal digits.  The tag
  76    00000 is special and means "does not have behaviour identical to any
  77    other replacement/wrapper function".  Hence if you wish to write a
  78    wrap/replacement function that is not subject to the above
  79    resolution rules, use 00000 for the tag.  Tags 00001 through 00009
  80    may not be used for any purpose.
  81
  82
  83    Replacement
  84    ~~~~~~~~~~~
  85    To write a replacement function, do this:
  86
  87       ret_type
  88       VG_REPLACE_FUNCTION_ZU(zEncodedSoname,fnname) ( .. args .. )
  89       {
  90          ... body ...
  91       }
  92
  93    zEncodedSoname should be a Z-encoded soname (see below for
  94    Z-encoding details) and fnname should be an unencoded fn name.  A
  95    default-safe equivalence tag of 00000 is assumed (see comments
  96    above).  The resulting name is
  97
  98       _vgr00000ZU_zEncodedSoname_fnname
  99
 100    The "_vgr00000ZU_" is a prefix that gets discarded upon decoding.
 101    It identifies this function as a replacement and specifies its
 102    equivalence tag.
 103
 104    It is also possible to write
 105
 106       ret_type
 107       VG_REPLACE_FUNCTION_ZZ(zEncodedSoname,zEncodedFnname) ( .. args .. )
 108       {
 109          ... body ...
 110       }
 111
 112    which means precisely the same, but the function name is also
 113    Z-encoded.  This can sometimes be necessary.  In this case the
 114    resulting function name is
 115
 116       _vgr00000ZZ_zEncodedSoname_zEncodedFnname
 117
 118    When it sees this either such name, the core's symbol-table reading
 119    machinery and redirection machinery first Z-decode the soname and
 120    if necessary the fnname.  They are encoded so that they may include
 121    arbitrary characters, and in particular they may contain '*', which
 122    acts as a wildcard.
 123
 124    They then will conspire to cause calls to any function matching
 125    'fnname' in any object whose soname matches 'soname' to actually be
 126    routed to this function.  This is used in Valgrind to define dozens
 127    of replacements of malloc, free, etc.
 128
 129    The soname must be a Z-encoded bit of text because sonames can
 130    contain dots etc which are not valid symbol names.  The function
 131    name may or may not be Z-encoded: to include wildcards it has to be,
 132    but Z-encoding C++ function names which are themselves already mangled
 133    using Zs in some way is tedious and error prone, so the _ZU variant
 134    allows them not to be Z-encoded.
 135
 136    Note that the soname "NONE" is specially interpreted to match any
 137    shared object which doesn't have a soname.
 138
 139    Note also that the replacement function should probably (must be?) in
 140    client space, so it runs on the simulated CPU.  So it must be in
 141    either vgpreload_<tool>.so or vgpreload_core.so.  It also only works
 142    with functions in shared objects, I think.
 143
 144    It is important that the Z-encoded names contain no unencoded
 145    underscores, since the intercept-handlers in m_redir.c detect the
 146    end of the soname by looking for the first trailing underscore.
 147
 148    To write function names which explicitly state the equivalence class
 149    tag, use
 150      VG_REPLACE_FUNCTION_EZU(5-digit-tag,zEncodedSoname,fnname)
 151    or
 152      VG_REPLACE_FUNCTION_EZZ(5-digit-tag,zEncodedSoname,zEncodedFnname)
 153
 154    As per comments above, the tag must be a 5 digit decimal number,
 155    padded with leading zeroes, in the range 00010 to 99999 inclusive.
 156
 157
 158    Wrapping
 159    ~~~~~~~~
 160    This is identical to replacement, except that you should use the
 161    macro names
 162
 163       VG_WRAP_FUNCTION_ZU
 164       VG_WRAP_FUNCTION_ZZ
 165       VG_WRAP_FUNCTION_EZU
 166       VG_WRAP_FUNCTION_EZZ
 167
 168    instead.
 169
 170    Z-encoding
 171    ~~~~~~~~~~
 172    Z-encoding details: the scheme is like GHC's.  It is just about
 173    readable enough to make a preprocessor unnecessary.  First the
 174    "_vgrZU_" or "_vgrZZ_" prefix is added, and then the following
 175    characters are transformed.
 176
 177      *         -->  Za    (asterisk)
 178      :         -->  Zc    (colon)
 179      .         -->  Zd    (dot)
 180      -         -->  Zh    (hyphen)
 181      +         -->  Zp    (plus)
 182      (space)   -->  Zs    (space)
 183      _         -->  Zu    (underscore)
 184      @         -->  ZA    (at)
 185      $         -->  ZD    (dollar)
 186      (         -->  ZL    (left)
 187      )         -->  ZR    (right)
 188      Z         -->  ZZ    (Z)
 189
 190    Everything else is left unchanged.
 191 */
 192
 193 /* If you change these, the code in VG_(maybe_Z_demangle) needs to be
 194    changed accordingly.  NOTE: duplicates
 195    I_{WRAP,REPLACE}_SONAME_FNNAME_Z{U,Z} in valgrind.h. */
 196
 197 /* Use an extra level of macroisation so as to ensure the soname/fnname
 198    args are fully macro-expanded before pasting them together. */
 199 #define VG_CONCAT4(_aa,_bb,_cc,_dd) _aa##_bb##_cc##_dd
 200
 201 #define VG_CONCAT6(_aa,_bb,_cc,_dd,_ee,_ff) _aa##_bb##_cc##_dd##_ee##_ff
 202
 203 /* The 4 basic macros. */
 204 #define VG_REPLACE_FUNCTION_EZU(_eclasstag,_soname,_fnname) \
 205    VG_CONCAT6(_vgr,_eclasstag,ZU_,_soname,_,_fnname)
 206
 207 #define VG_REPLACE_FUNCTION_EZZ(_eclasstag,_soname,_fnname) \
 208    VG_CONCAT6(_vgr,_eclasstag,ZZ_,_soname,_,_fnname)
 209
 210 #define VG_WRAP_FUNCTION_EZU(_eclasstag,_soname,_fnname) \
 211    VG_CONCAT6(_vgw,_eclasstag,ZU_,_soname,_,_fnname)
 212
 213 #define VG_WRAP_FUNCTION_EZZ(_eclasstag,_soname,_fnname) \
 214    VG_CONCAT6(_vgw,_eclasstag,ZZ_,_soname,_,_fnname)
 215
 216 /* Convenience macros defined in terms of the above 4. */
 217 #define VG_REPLACE_FUNCTION_ZU(_soname,_fnname) \
 218    VG_CONCAT6(_vgr,00000,ZU_,_soname,_,_fnname)
 219
 220 #define VG_REPLACE_FUNCTION_ZZ(_soname,_fnname) \
 221    VG_CONCAT6(_vgr,00000,ZZ_,_soname,_,_fnname)
 222
 223 #define VG_WRAP_FUNCTION_ZU(_soname,_fnname) \
 224    VG_CONCAT6(_vgw,00000,ZU_,_soname,_,_fnname)
 225
 226 #define VG_WRAP_FUNCTION_ZZ(_soname,_fnname) \
 227    VG_CONCAT6(_vgw,00000,ZZ_,_soname,_,_fnname)
 228
 229
 230 /* --------- Some handy Z-encoded names. --------- */
 231
 232 // Nb: ALL THESE NAMES MUST BEGIN WITH "VG_Z_".  Why?  If we applied
 233 // conditional compilation inconsistently we could accidentally use an
 234 // undefined constant like VG_Z_LIBC_DOT_A, resulting in a bogus Z-encoded
 235 // name like "_vgrZU_VG_Z_LIBC_DOT_A_foo".  This can't be detected at
 236 // compile-time, because both the constant's name and its value are
 237 // identifiers.  However, by always using "VG_Z_" as a prefix, we can do a
 238 // run-time check and abort if any name has "VG_Z_" in it, because that
 239 // indicates that the constant has been used without being defined.
 240
 241 /* --- Soname of the standard C library. --- */
 242
 243 #if defined(VGO_linux)
 244 #  define  VG_Z_LIBC_SONAME  libcZdsoZa              // libc.so*
 245
 246 #elif defined(VGO_darwin) && (DARWIN_VERS <= DARWIN_10_6)
 247 #  define  VG_Z_LIBC_SONAME  libSystemZdZaZddylib    // libSystem.*.dylib
 248
 249 #elif defined(VGO_darwin) && (DARWIN_VERS == DARWIN_10_7 \
 250                               || DARWIN_VERS == DARWIN_10_8)
 251 #  define  VG_Z_LIBC_SONAME  libsystemZucZaZddylib   // libsystem_c*.dylib
 252    /* Note that the idea of a single name for the C library falls
 253       apart on more recent Darwins (10.8 and later) since the
 254       functionality (malloc, free, str*) is split between
 255       libsystem_c.dylib, libsystem_malloc.dylib and
 256       libsystem_platform.dylib.  This makes VG_Z_LIBC_SONAME somewhat useless
 257       at least inside vg_replace_strmem.c, and that hardwires some dylib
 258       names directly, for OSX 10.9. */
 259
 260 #elif defined(VGO_darwin) && (DARWIN_VERS >= DARWIN_10_9)
 261 #  define  VG_Z_LIBC_SONAME  libsystemZumallocZddylib  // libsystem_malloc.dylib
 262
 263 #else
 264 #  error "Unknown platform"
 265
 266 #endif
 267
 268 /* --- Soname of the GNU C++ library. --- */
 269
 270 // Valid on all platforms(?)
 271 #define  VG_Z_LIBSTDCXX_SONAME  libstdcZpZpZa           // libstdc++*
 272
 273 /* --- Soname of the pthreads library. --- */
 274
 275 #if defined(VGO_linux)
 276 #  define  VG_Z_LIBPTHREAD_SONAME  libpthreadZdsoZd0     // libpthread.so.0
 277 #elif defined(VGO_darwin)
 278 #  define  VG_Z_LIBPTHREAD_SONAME  libSystemZdZaZddylib  // libSystem.*.dylib
 279 #else
 280 #  error "Unknown platform"
 281 #endif
 282
 283 /* --- Sonames for Linux ELF linkers, plus unencoded versions. --- */
 284
 285 #if defined(VGO_linux)
 286
 287 #define  VG_Z_LD_LINUX_SO_3         ldZhlinuxZdsoZd3           // ld-linux.so.3
 288 #define  VG_U_LD_LINUX_SO_3         "ld-linux.so.3"
 289
 290 #define  VG_Z_LD_LINUX_SO_2         ldZhlinuxZdsoZd2           // ld-linux.so.2
 291 #define  VG_U_LD_LINUX_SO_2         "ld-linux.so.2"
 292
 293 #define  VG_Z_LD_LINUX_X86_64_SO_2  ldZhlinuxZhx86Zh64ZdsoZd2
 294                                                         // ld-linux-x86-64.so.2
 295 #define  VG_U_LD_LINUX_X86_64_SO_2  "ld-linux-x86-64.so.2"
 296
 297 #define  VG_Z_LD64_SO_1             ld64ZdsoZd1                // ld64.so.1
 298 #define  VG_U_LD64_SO_1             "ld64.so.1"
 299 #define  VG_U_LD64_SO_2             "ld64.so.2"                // PPC LE loader
 300
 301 #define  VG_Z_LD_SO_1               ldZdsoZd1                  // ld.so.1
 302 #define  VG_U_LD_SO_1               "ld.so.1"
 303
 304 #define  VG_U_LD_LINUX_AARCH64_SO_1 "ld-linux-aarch64.so.1"
 305 #define  VG_U_LD_LINUX_ARMHF_SO_3   "ld-linux-armhf.so.3"
 306
 307 #endif
 308
 309 /* --- Executable name for Darwin Mach-O linker. --- */
 310
 311 #if defined(VGO_darwin)
 312
 313 #define  VG_Z_DYLD               dyld                       // dyld
 314 #define  VG_U_DYLD               "dyld"
 315
 316 #endif
 317
 318
 319 // Prefix for synonym soname synonym handling
 320 #define VG_SO_SYN(name)       VgSoSyn##name
 321 #define VG_SO_SYN_PREFIX     "VgSoSyn"
 322 #define VG_SO_SYN_PREFIX_LEN 7
 323
 324 #endif   // __PUB_TOOL_REDIR_H
 325
 326 /*--------------------------------------------------------------------*/
 327 /*--- end                                                          ---*/
 328 /*--------------------------------------------------------------------*/