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