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 #if defined(VGP_amd64_freebsd)
 237       char  padding[7];
 238 #else
 239       char  padding[3];
 240 #endif
 241    }
 242    SysRes;
 243
 244 #elif defined(VGO_solaris)
 245 typedef
 246    struct {
 247       UWord _val;
 248       UWord _val2;
 249       Bool  _isError;
 250    }
 251    SysRes;
 252
 253 #else
 254 #  error "Unknown OS"
 255 #endif
 256
 257
 258 /* ---- And now some basic accessor functions for it. ---- */
 259
 260 #if defined(VGP_mips32_linux) || defined(VGP_mips64_linux)
 261
 262 static inline Bool sr_isError ( SysRes sr ) {
 263    return sr._isError;
 264 }
 265 static inline RegWord sr_Res ( SysRes sr ) {
 266    return sr._isError ? 0 : sr._val;
 267 }
 268 static inline UWord sr_ResEx ( SysRes sr ) {
 269    return sr._isError ? 0 : sr._valEx;
 270 }
 271 static inline UWord sr_Err ( SysRes sr ) {
 272    return sr._isError ? sr._val : 0;
 273 }
 274 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 275    /* This uglyness of hardcoding syscall numbers is necessary to
 276       avoid having this header file be dependent on
 277       include/vki/vki-scnums-mips{32,64}-linux.h.  It seems pretty
 278       safe given that it is inconceivable that the syscall numbers
 279       for such simple syscalls would ever change.  To make it
 280       really safe, coregrind/m_vkiscnums.c static-asserts that these
 281       syscall numbers haven't changed, so that the build wil simply
 282       fail if they ever do. */
 283 #  if defined(VGP_mips32_linux)
 284    const UInt __nr_Linux = 4000;
 285    const UInt __nr_pipe  = __nr_Linux + 42;
 286    const UInt __nr_pipe2 = __nr_Linux + 328;
 287 #  elif defined(VGP_mips64_linux) && defined(VGABI_N32)
 288    const UInt __nr_Linux = 6000;
 289    const UInt __nr_pipe  = __nr_Linux + 21;
 290    const UInt __nr_pipe2 = __nr_Linux + 291;
 291 #  else
 292    const UInt __nr_Linux = 5000;
 293    const UInt __nr_pipe  = __nr_Linux + 21;
 294    const UInt __nr_pipe2 = __nr_Linux + 287;
 295 #  endif
 296    Bool useEx = sysno == __nr_pipe || sysno == __nr_pipe2;
 297    return sr1._val == sr2._val
 298           && (useEx ? (sr1._valEx == sr2._valEx) : True)
 299           && sr1._isError == sr2._isError;
 300 }
 301
 302 #elif defined(VGO_linux) \
 303       && !defined(VGP_mips32_linux) && !defined(VGP_mips64_linux)
 304
 305 static inline Bool sr_isError ( SysRes sr ) {
 306    return sr._isError;
 307 }
 308 static inline UWord sr_Res ( SysRes sr ) {
 309    return sr._isError ? 0 : sr._val;
 310 }
 311 static inline UWord sr_Err ( SysRes sr ) {
 312 #if defined(VGP_nanomips_linux)
 313    return sr._isError ? -sr._val : 0;
 314 #else
 315    return sr._isError ? sr._val : 0;
 316 #endif
 317 }
 318 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 319    /* sysno is ignored for Linux/not-MIPS */
 320    return sr1._val == sr2._val
 321           && sr1._isError == sr2._isError;
 322 }
 323
 324 #elif defined(VGO_freebsd)
 325
 326 static inline Bool sr_isError ( SysRes sr ) {
 327    return sr._isError;
 328 }
 329 static inline UWord sr_Res ( SysRes sr ) {
 330    return sr._isError ? 0 : sr._val;
 331 }
 332 static inline UWord sr_ResHI ( SysRes sr ) {
 333    return sr._isError ? 0 : sr._val2;
 334 }
 335 static inline UWord sr_Err ( SysRes sr ) {
 336    return sr._isError ? sr._val : 0;
 337 }
 338 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 339    return sr_Res(sr1) == sr_Res(sr2)
 340           && sr_ResHI(sr1) == sr_ResHI(sr2)
 341           && ((sr_isError(sr1) && sr_isError(sr2))
 342               || (!sr_isError(sr1) && !sr_isError(sr2)));
 343 }
 344
 345 #elif defined(VGO_darwin)
 346
 347 static inline Bool sr_isError ( SysRes sr ) {
 348    switch (sr._mode) {
 349       case SysRes_UNIX_ERR:
 350          return True;
 351       /* should check tags properly and assert here, but we can't here */
 352       case SysRes_MACH:
 353       case SysRes_MDEP:
 354       case SysRes_UNIX_OK:
 355       default:
 356          return False;
 357    }
 358 }
 359
 360 static inline UWord sr_Res ( SysRes sr ) {
 361    switch (sr._mode) {
 362       case SysRes_MACH:
 363       case SysRes_MDEP:
 364       case SysRes_UNIX_OK:
 365          return sr._wLO;
 366       /* should assert, but we can't here */
 367       case SysRes_UNIX_ERR:
 368       default:
 369          return 0;
 370    }
 371 }
 372
 373 static inline UWord sr_ResHI ( SysRes sr ) {
 374    switch (sr._mode) {
 375       case SysRes_UNIX_OK:
 376          return sr._wHI;
 377       /* should assert, but we can't here */
 378       case SysRes_MACH:
 379       case SysRes_MDEP:
 380       case SysRes_UNIX_ERR:
 381       default:
 382          return 0;
 383    }
 384 }
 385
 386 static inline UWord sr_Err ( SysRes sr ) {
 387    switch (sr._mode) {
 388       case SysRes_UNIX_ERR:
 389          return sr._wLO;
 390       /* should assert, but we can't here */
 391       case SysRes_MACH:
 392       case SysRes_MDEP:
 393       case SysRes_UNIX_OK:
 394       default:
 395          return 0;
 396    }
 397 }
 398
 399 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 400    /* sysno is ignored for Darwin */
 401    return sr1._mode == sr2._mode
 402           && sr1._wLO == sr2._wLO && sr1._wHI == sr2._wHI;
 403 }
 404
 405 #elif defined(VGO_solaris)
 406
 407 static inline Bool sr_isError ( SysRes sr ) {
 408    return sr._isError;
 409 }
 410 static inline UWord sr_Res ( SysRes sr ) {
 411    return sr._isError ? 0 : sr._val;
 412 }
 413 static inline UWord sr_ResHI ( SysRes sr ) {
 414    return sr._isError ? 0 : sr._val2;
 415 }
 416 static inline UWord sr_Err ( SysRes sr ) {
 417    return sr._isError ? sr._val : 0;
 418 }
 419 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 420    /* sysno is ignored for Solaris */
 421    return sr1._val == sr2._val
 422        && sr1._isError == sr2._isError
 423        && (!sr1._isError) ? (sr1._val2 == sr2._val2) : True;
 424 }
 425
 426 #else
 427 #  error "Unknown OS"
 428 #endif
 429
 430
 431 /* ---------------------------------------------------------------------
 432    Miscellaneous (word size, endianness, regparmness, stringification)
 433    ------------------------------------------------------------------ */
 434
 435 /* Word size: this is going to be either 4 or 8. */
 436 // It should probably be in m_machine.
 437 #define VG_WORDSIZE VEX_HOST_WORDSIZE
 438
 439 /* Endianness */
 440 #undef VG_BIGENDIAN
 441 #undef VG_LITTLEENDIAN
 442
 443 #if defined(VGA_x86) || defined(VGA_amd64) || defined (VGA_arm) \
 444     || ((defined(VGA_mips32) || defined(VGA_mips64) || defined(VGA_nanomips)) \
 445     && defined (_MIPSEL)) || defined(VGA_arm64)  || defined(VGA_ppc64le)
 446 #  define VG_LITTLEENDIAN 1
 447 #elif defined(VGA_ppc32) || defined(VGA_ppc64be) || defined(VGA_s390x) \
 448       || ((defined(VGA_mips32) || defined(VGA_mips64) || defined(VGA_nanomips)) \
 449       && defined (_MIPSEB))
 450 #  define VG_BIGENDIAN 1
 451 #else
 452 #  error Unknown arch
 453 #endif
 454
 455 /* Offsetof */
 456 #if !defined(offsetof)
 457 #   define offsetof(type,memb) ((SizeT)(HWord)&((type*)0)->memb)
 458 #endif
 459
 460 #if !defined(container_of)
 461 #   define container_of(ptr, type, member) ((type *)((char *)(ptr) - offsetof(type, member)))
 462 #endif
 463
 464 /* Alignment */
 465 /* We use a prefix vg_ for vg_alignof as its behaviour slightly
 466    differs from the standard alignof/gcc defined __alignof__
 467
 468    vg_alignof returns a "safe" alignement.
 469    "safe" is defined as the alignment chosen by the compiler in
 470    a struct made of a char followed by this type.
 471
 472       Note that this is not necessarily the "preferred" alignment
 473       for a platform. This preferred alignment is returned by the gcc
 474        __alignof__ and by the standard (in recent standard) alignof.
 475       Compared to __alignof__, vg_alignof gives on some platforms (e.g.
 476       amd64, ppc32, ppc64) a bigger alignment for long double (16 bytes
 477       instead of 8).
 478       On some platforms (e.g. x86), vg_alignof gives a smaller alignment
 479       than __alignof__ for long long and double (4 bytes instead of 8).
 480       If we want to have the "preferred" alignment for the basic types,
 481       then either we need to depend on gcc __alignof__, or on a (too)
 482       recent standard and compiler (implementing <stdalign.h>).
 483 */
 484 #define vg_alignof(_type) (sizeof(struct {char c;_type _t;})-sizeof(_type))
 485
 486 /* Regparmness */
 487 #if defined(VGA_x86)
 488 #  define VG_REGPARM(n)            __attribute__((regparm(n)))
 489 #elif defined(VGA_amd64) || defined(VGA_ppc32) \
 490       || defined(VGA_ppc64be) || defined(VGA_ppc64le) \
 491       || defined(VGA_arm) || defined(VGA_s390x) \
 492       || defined(VGA_mips32) || defined(VGA_mips64) \
 493       || defined(VGA_arm64) || defined(VGA_nanomips)
 494 #  define VG_REGPARM(n)            /* */
 495 #else
 496 #  error Unknown arch
 497 #endif
 498
 499 /* Macro games */
 500 #define VG_STRINGIFZ(__str)  #__str
 501 #define VG_STRINGIFY(__str)  VG_STRINGIFZ(__str)
 502
 503 // Where to send bug reports to.
 504 #define VG_BUGS_TO "www.valgrind.org"
 505
 506 /* Branch prediction hints. */
 507 #if defined(__GNUC__)
 508 #  define LIKELY(x)   __builtin_expect(!!(x), 1)
 509 #  define UNLIKELY(x) __builtin_expect(!!(x), 0)
 510 #else
 511 #  define LIKELY(x)   (x)
 512 #  define UNLIKELY(x) (x)
 513 #endif
 514
 515 // printf format string checking for gcc.
 516 // This feature has been supported since at least gcc version 2.95.
 517 // For more information about the format attribute, see
 518 // http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Function-Attributes.html.
 519 #if defined(__GNUC__)
 520 #define PRINTF_CHECK(x, y) __attribute__((format(__printf__, x, y)))
 521 #else
 522 #define PRINTF_CHECK(x, y)
 523 #endif
 524
 525 // Macro to "cast" away constness (from type const T to type T) without
 526 // GCC complaining about it. This macro should be used RARELY.
 527 // x is expected to have type const T
 528 #define CONST_CAST(T,x)    \
 529    ({                      \
 530       union {              \
 531          const T in;      \
 532          T out;           \
 533       } var = { .in = x }; var.out;  \
 534    })
 535
 536 /* Some architectures (eg. mips, arm) do not support unaligned memory access
 537    by hardware, so GCC warns about suspicious situations. This macro could
 538    be used to avoid these warnings but only after careful examination. */
 539 #define ASSUME_ALIGNED(D, x)                 \
 540    ({                                        \
 541       union {                                \
 542          void *in;                           \
 543          D out;                              \
 544       } var;                                 \
 545       var.in = (void *) (x); var.out;        \
 546    })
 547
 548 // Poor man's static assert
 549 #define STATIC_ASSERT(x)  extern int VG_(VG_(VG_(unused)))[(x) ? 1 : -1] \
 550                                      __attribute__((unused))
 551
 552 #define VG_MAX(a,b) ((a) > (b) ? a : b)
 553 #define VG_MIN(a,b) ((a) < (b) ? a : b)
 554
 555 #endif /* __PUB_TOOL_BASICS_H */
 556
 557 /*--------------------------------------------------------------------*/
 558 /*--- end                                                          ---*/
 559 /*--------------------------------------------------------------------*/