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