include/pub_tool_basics.h

   1
   2 /*--------------------------------------------------------------------*/
   3 /*--- Header included by every tool C file.      pub_tool_basics.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_BASICS_H
  32 #define __PUB_TOOL_BASICS_H
  33
  34 //--------------------------------------------------------------------
  35 // PURPOSE: This header should be imported by every single C file in
  36 // tools.  It contains the basic types and other things needed everywhere.
  37 // There is no corresponding C file because this isn't a module
  38 // containing executable code, it's all just declarations.
  39 //--------------------------------------------------------------------
  40
  41 /* ---------------------------------------------------------------------
  42    Other headers to include
  43    ------------------------------------------------------------------ */
  44
  45 // VEX defines Char, UChar, Short, UShort, Int, UInt, Long, ULong, SizeT,
  46 // Addr, Addr32, Addr64, HWord, HChar, Bool, False and True.
  47 #include "libvex_basictypes.h"
  48
  49 // For varargs types
  50 #include <stdarg.h>
  51
  52
  53 /* ---------------------------------------------------------------------
  54    symbol prefixing
  55    ------------------------------------------------------------------ */
  56
  57 // All symbols externally visible from Valgrind are prefixed
  58 // as specified here to avoid namespace conflict problems.
  59 //
  60 // VG_ is for symbols exported from modules.  ML_ (module-local) is
  61 // for symbols which are not intended to be visible outside modules,
  62 // but which cannot be declared as C 'static's since they need to be
  63 // visible across C files within a given module.  It is a mistake for
  64 // a ML_ name to appear in a pub_core_*.h or pub_tool_*.h file.
  65 // Likewise it is a mistake for a VG_ name to appear in a priv_*.h
  66 // file.
  67
  68 #define VGAPPEND(str1,str2) str1##str2
  69
  70 #define VG_(str)    VGAPPEND(vgPlain_,          str)
  71 #define ML_(str)    VGAPPEND(vgModuleLocal_,    str)
  72
  73
  74 /* ---------------------------------------------------------------------
  75    builtin types
  76    ------------------------------------------------------------------ */
  77
  78 // By choosing the right types, we can get these right for 32-bit and 64-bit
  79 // platforms without having to do any conditional compilation or anything.
  80 // POSIX references:
  81 // - http://www.opengroup.org/onlinepubs/009695399/basedefs/sys/types.h.html
  82 // - http://www.opengroup.org/onlinepubs/009695399/basedefs/stddef.h.html
  83 //
  84 // Size in bits on:                          32-bit archs   64-bit archs
  85 //                                           ------------   ------------
  86 typedef unsigned long          UWord;     // 32             64
  87 typedef   signed long           Word;     // 32             64
  88
  89 // Our equivalent of POSIX 'ssize_t':
  90 // - ssize_t is "used for a count of bytes or an error indication".
  91 typedef  Word                 SSizeT;     // 32             64
  92
  93 // Our equivalent of POSIX 'ptrdiff_t':
  94 // - ptrdiff_t is a "signed integer type of the result of subtracting two
  95 //   pointers".
  96 // We use it for memory offsets, eg. the offset into a memory block.
  97 typedef  Word                 PtrdiffT;   // 32             64
  98
  99 // Our equivalent of POSIX 'off_t':
 100 // - off_t is "used for file sizes".
 101 // At one point we were using it for memory offsets, but PtrdiffT should be
 102 // used in those cases.
 103 // Nb: on Linux, off_t is a signed word-sized int.  On Darwin it's
 104 // always a signed 64-bit int.  So we defined our own Off64T as well.
 105 #if defined(VGO_linux) || defined(VGO_solaris)
 106 typedef Word                   OffT;      // 32             64
 107 #elif defined(VGO_darwin)
 108 typedef Long                   OffT;      // 64             64
 109 #else
 110 #  error Unknown OS
 111 #endif
 112 typedef Long                 Off64T;      // 64             64
 113
 114 #if !defined(NULL)
 115 #  define NULL ((void*)0)
 116 #endif
 117
 118 /* This is just too useful to not have around the place somewhere. */
 119 typedef  struct { UWord uw1; UWord uw2; }  UWordPair;
 120
 121
 122 /* ---------------------------------------------------------------------
 123    non-builtin types
 124    ------------------------------------------------------------------ */
 125
 126 // These probably shouldn't be here, but moving them to their logical
 127 // modules results in a lot more #includes...
 128
 129 /* ThreadIds are simply indices into the VG_(threads)[] array. */
 130 typedef UInt ThreadId;
 131
 132 /* An abstraction of syscall return values.
 133    Linux/MIPS32 and Linux/MIPS64:
 134       When _isError == False,
 135          _val and possible _valEx hold the return value.  Whether
 136          _valEx actually holds a valid value depends on which syscall
 137          this SysRes holds of the result of.
 138       When _isError == True,
 139          _val holds the error code.
 140
 141    Linux/other:
 142       When _isError == False,
 143          _val holds the return value.
 144       When _isError == True,
 145          _val holds the error code.
 146
 147    Darwin:
 148       Interpretation depends on _mode:
 149       MACH, MDEP:
 150          these can never 'fail' (apparently).  The result of the
 151          syscall is a single host word, _wLO.
 152       UNIX:
 153          Can record a double-word error or a double-word result:
 154          When _mode is SysRes_UNIX_OK,  _wHI:_wLO holds the result.
 155          When _mode is SysRes_UNIX_ERR, _wHI:_wLO holds the error code.
 156          Probably the high word of an error is always ignored by
 157          userspace, but we have to record it, so that we can correctly
 158          update both {R,E}DX and {R,E}AX (in guest state) given a SysRes,
 159          if we're required to.
 160
 161    Solaris:
 162       When _isError == False,
 163          _val and _val2 hold the return value.
 164       When _isError == True,
 165          _val holds the error code.
 166 */
 167 #if defined(VGP_mips32_linux) || defined(VGP_mips64_linux)
 168 typedef
 169    struct {
 170       Bool  _isError;
 171       UWord _val;
 172       UWord _valEx;
 173    }
 174    SysRes;
 175
 176 #elif defined(VGO_linux) \
 177       && !defined(VGP_mips32_linux) && !defined(VGP_mips64_linux)
 178 typedef
 179    struct {
 180       Bool  _isError;
 181       UWord _val;
 182    }
 183    SysRes;
 184
 185 #elif defined(VGO_darwin)
 186 typedef
 187    enum {
 188       SysRes_MACH=40,  // MACH, result is _wLO
 189       SysRes_MDEP,     // MDEP, result is _wLO
 190       SysRes_UNIX_OK,  // UNIX, success, result is _wHI:_wLO
 191       SysRes_UNIX_ERR  // UNIX, error,   error  is _wHI:_wLO
 192    }
 193    SysResMode;
 194 typedef
 195    struct {
 196       UWord _wLO;
 197       UWord _wHI;
 198       SysResMode _mode;
 199    }
 200    SysRes;
 201
 202 #elif defined(VGO_solaris)
 203 typedef
 204    struct {
 205       UWord _val;
 206       UWord _val2;
 207       Bool  _isError;
 208    }
 209    SysRes;
 210
 211 #else
 212 #  error "Unknown OS"
 213 #endif
 214
 215
 216 /* ---- And now some basic accessor functions for it. ---- */
 217
 218 #if defined(VGP_mips32_linux) || defined(VGP_mips64_linux)
 219
 220 static inline Bool sr_isError ( SysRes sr ) {
 221    return sr._isError;
 222 }
 223 static inline UWord sr_Res ( SysRes sr ) {
 224    return sr._isError ? 0 : sr._val;
 225 }
 226 static inline UWord sr_ResEx ( SysRes sr ) {
 227    return sr._isError ? 0 : sr._valEx;
 228 }
 229 static inline UWord sr_Err ( SysRes sr ) {
 230    return sr._isError ? sr._val : 0;
 231 }
 232 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 233    /* This uglyness of hardcoding syscall numbers is necessary to
 234       avoid having this header file be dependant on
 235       include/vki/vki-scnums-mips{32,64}-linux.h.  It seems pretty
 236       safe given that it is inconceivable that the syscall numbers
 237       for such simple syscalls would ever change.  To make it
 238       really safe, coregrind/m_vkiscnums.c static-asserts that these
 239       syscall numbers haven't changed, so that the build wil simply
 240       fail if they ever do. */
 241 #  if defined(VGP_mips32_linux)
 242    const UInt __nr_Linux = 4000;
 243    const UInt __nr_pipe  = __nr_Linux + 42;
 244    const UInt __nr_pipe2 = __nr_Linux + 328;
 245 #  else
 246    const UInt __nr_Linux = 5000;
 247    const UInt __nr_pipe  = __nr_Linux + 21;
 248    const UInt __nr_pipe2 = __nr_Linux + 287;
 249 #  endif
 250    Bool useEx = sysno == __nr_pipe || sysno == __nr_pipe2;
 251    return sr1._val == sr2._val
 252           && (useEx ? (sr1._valEx == sr2._valEx) : True)
 253           && sr1._isError == sr2._isError;
 254 }
 255
 256 #elif defined(VGO_linux) \
 257       && !defined(VGP_mips32_linux) && !defined(VGP_mips64_linux)
 258
 259 static inline Bool sr_isError ( SysRes sr ) {
 260    return sr._isError;
 261 }
 262 static inline UWord sr_Res ( SysRes sr ) {
 263    return sr._isError ? 0 : sr._val;
 264 }
 265 static inline UWord sr_Err ( SysRes sr ) {
 266    return sr._isError ? sr._val : 0;
 267 }
 268 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 269    /* sysno is ignored for Linux/not-MIPS */
 270    return sr1._val == sr2._val
 271           && sr1._isError == sr2._isError;
 272 }
 273
 274 #elif defined(VGO_darwin)
 275
 276 static inline Bool sr_isError ( SysRes sr ) {
 277    switch (sr._mode) {
 278       case SysRes_UNIX_ERR:
 279          return True;
 280       /* should check tags properly and assert here, but we can't here */
 281       case SysRes_MACH:
 282       case SysRes_MDEP:
 283       case SysRes_UNIX_OK:
 284       default:
 285          return False;
 286    }
 287 }
 288
 289 static inline UWord sr_Res ( SysRes sr ) {
 290    switch (sr._mode) {
 291       case SysRes_MACH:
 292       case SysRes_MDEP:
 293       case SysRes_UNIX_OK:
 294          return sr._wLO;
 295       /* should assert, but we can't here */
 296       case SysRes_UNIX_ERR:
 297       default:
 298          return 0;
 299    }
 300 }
 301
 302 static inline UWord sr_ResHI ( SysRes sr ) {
 303    switch (sr._mode) {
 304       case SysRes_UNIX_OK:
 305          return sr._wHI;
 306       /* should assert, but we can't here */
 307       case SysRes_MACH:
 308       case SysRes_MDEP:
 309       case SysRes_UNIX_ERR:
 310       default:
 311          return 0;
 312    }
 313 }
 314
 315 static inline UWord sr_Err ( SysRes sr ) {
 316    switch (sr._mode) {
 317       case SysRes_UNIX_ERR:
 318          return sr._wLO;
 319       /* should assert, but we can't here */
 320       case SysRes_MACH:
 321       case SysRes_MDEP:
 322       case SysRes_UNIX_OK:
 323       default:
 324          return 0;
 325    }
 326 }
 327
 328 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 329    /* sysno is ignored for Darwin */
 330    return sr1._mode == sr2._mode
 331           && sr1._wLO == sr2._wLO && sr1._wHI == sr2._wHI;
 332 }
 333
 334 #elif defined(VGO_solaris)
 335
 336 static inline Bool sr_isError ( SysRes sr ) {
 337    return sr._isError;
 338 }
 339 static inline UWord sr_Res ( SysRes sr ) {
 340    return sr._isError ? 0 : sr._val;
 341 }
 342 static inline UWord sr_ResHI ( SysRes sr ) {
 343    return sr._isError ? 0 : sr._val2;
 344 }
 345 static inline UWord sr_Err ( SysRes sr ) {
 346    return sr._isError ? sr._val : 0;
 347 }
 348 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 349    /* sysno is ignored for Solaris */
 350    return sr1._val == sr2._val
 351        && sr1._val2 == sr2._val2
 352        && sr1._isError == sr2._isError;
 353 }
 354
 355 #else
 356 #  error "Unknown OS"
 357 #endif
 358
 359
 360 /* ---------------------------------------------------------------------
 361    Miscellaneous (word size, endianness, regparmness, stringification)
 362    ------------------------------------------------------------------ */
 363
 364 /* Word size: this is going to be either 4 or 8. */
 365 // It should probably be in m_machine.
 366 #define VG_WORDSIZE VEX_HOST_WORDSIZE
 367
 368 /* Endianness */
 369 #undef VG_BIGENDIAN
 370 #undef VG_LITTLEENDIAN
 371
 372 #if defined(VGA_x86) || defined(VGA_amd64) || defined (VGA_arm) \
 373     || ((defined(VGA_mips32) || defined(VGA_mips64)) && defined (_MIPSEL)) \
 374     || defined(VGA_arm64)  || defined(VGA_ppc64le) || defined(VGA_tilegx)
 375 #  define VG_LITTLEENDIAN 1
 376 #elif defined(VGA_ppc32) || defined(VGA_ppc64be) || defined(VGA_s390x) \
 377       || ((defined(VGA_mips32) || defined(VGA_mips64)) && defined (_MIPSEB))
 378 #  define VG_BIGENDIAN 1
 379 #else
 380 #  error Unknown arch
 381 #endif
 382
 383 /* Offsetof */
 384 #if !defined(offsetof)
 385 #   define offsetof(type,memb) ((SizeT)(HWord)&((type*)0)->memb)
 386 #endif
 387
 388 /* Alignment */
 389 /* We use a prefix vg_ for vg_alignof as its behaviour slightly
 390    differs from the standard alignof/gcc defined __alignof__
 391
 392    vg_alignof returns a "safe" alignement.
 393    "safe" is defined as the alignment chosen by the compiler in
 394    a struct made of a char followed by this type.
 395
 396       Note that this is not necessarily the "preferred" alignment
 397       for a platform. This preferred alignment is returned by the gcc
 398        __alignof__ and by the standard (in recent standard) alignof.
 399       Compared to __alignof__, vg_alignof gives on some platforms (e.g.
 400       amd64, ppc32, ppc64) a bigger alignment for long double (16 bytes
 401       instead of 8).
 402       On some platforms (e.g. x86), vg_alignof gives a smaller alignment
 403       than __alignof__ for long long and double (4 bytes instead of 8).
 404       If we want to have the "preferred" alignment for the basic types,
 405       then either we need to depend on gcc __alignof__, or on a (too)
 406       recent standard and compiler (implementing <stdalign.h>).
 407 */
 408 #define vg_alignof(_type) (sizeof(struct {char c;_type _t;})-sizeof(_type))
 409
 410 /* Regparmness */
 411 #if defined(VGA_x86)
 412 #  define VG_REGPARM(n)            __attribute__((regparm(n)))
 413 #elif defined(VGA_amd64) || defined(VGA_ppc32) \
 414       || defined(VGA_ppc64be) || defined(VGA_ppc64le) \
 415       || defined(VGA_arm) || defined(VGA_s390x) \
 416       || defined(VGA_mips32) || defined(VGA_mips64) \
 417       || defined(VGA_arm64) || defined(VGA_tilegx)
 418 #  define VG_REGPARM(n)            /* */
 419 #else
 420 #  error Unknown arch
 421 #endif
 422
 423 /* Macro games */
 424 #define VG_STRINGIFZ(__str)  #__str
 425 #define VG_STRINGIFY(__str)  VG_STRINGIFZ(__str)
 426
 427 // Where to send bug reports to.
 428 #define VG_BUGS_TO "www.valgrind.org"
 429
 430 /* Branch prediction hints. */
 431 #if defined(__GNUC__)
 432 #  define LIKELY(x)   __builtin_expect(!!(x), 1)
 433 #  define UNLIKELY(x) __builtin_expect(!!(x), 0)
 434 #else
 435 #  define LIKELY(x)   (x)
 436 #  define UNLIKELY(x) (x)
 437 #endif
 438
 439 // printf format string checking for gcc.
 440 // This feature has been supported since at least gcc version 2.95.
 441 // For more information about the format attribute, see
 442 // http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Function-Attributes.html.
 443 #if defined(__GNUC__)
 444 #define PRINTF_CHECK(x, y) __attribute__((format(__printf__, x, y)))
 445 #else
 446 #define PRINTF_CHECK(x, y)
 447 #endif
 448
 449 // Macro to "cast" away constness (from type const T to type T) without
 450 // GCC complaining about it. This macro should be used RARELY.
 451 // x is expected to have type const T
 452 #define CONST_CAST(T,x)    \
 453    ({                      \
 454       union {              \
 455          const T in;      \
 456          T out;           \
 457       } var = { .in = x }; var.out;  \
 458    })
 459
 460 // Poor man's static assert
 461 #define STATIC_ASSERT(x)  extern int VG_(VG_(VG_(unused)))[(x) ? 1 : -1] \
 462                                      __attribute__((unused))
 463
 464 #endif /* __PUB_TOOL_BASICS_H */
 465
 466 /*--------------------------------------------------------------------*/
 467 /*--- end                                                          ---*/
 468 /*--------------------------------------------------------------------*/