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_darwin)
 106 typedef Long                   OffT;      // 64             64
 107 #else
 108 #  error Unknown OS
 109 #endif
 110 typedef Long                 Off64T;      // 64             64
 111
 112 #if !defined(NULL)
 113 #  define NULL ((void*)0)
 114 #endif
 115
 116 /* This is just too useful to not have around the place somewhere. */
 117 typedef  struct { UWord uw1; UWord uw2; }  UWordPair;
 118
 119
 120 /* ---------------------------------------------------------------------
 121    non-builtin types
 122    ------------------------------------------------------------------ */
 123
 124 // These probably shouldn't be here, but moving them to their logical
 125 // modules results in a lot more #includes...
 126
 127 /* ThreadIds are simply indices into the VG_(threads)[] array. */
 128 typedef UInt ThreadId;
 129
 130
 131 /* You need a debuginfo epoch in order to convert an address into any source
 132    level entity, since that conversion depends on what objects were mapped
 133    in at the time.  An epoch is simply a monotonically increasing counter,
 134    which we wrap up in a struct so as to enable the C type system to
 135    distinguish it from other kinds of numbers.  m_debuginfo holds and
 136    maintains the current epoch number. */
 137 typedef  struct { UInt n; }  DiEpoch;
 138
 139 static inline DiEpoch DiEpoch_INVALID ( void ) {
 140    DiEpoch dep; dep.n = 0; return dep;
 141 }
 142
 143 static inline Bool is_DiEpoch_INVALID ( DiEpoch dep ) {
 144    return dep.n == 0;
 145 }
 146
 147
 148 /* Many data structures need to allocate and release memory.
 149    The allocation/release functions must be provided by the caller.
 150    The Alloc_Fn_t function must allocate a chunk of memory of size szB.
 151    cc is the Cost Centre for this allocated memory. This constant string
 152    is used to provide Valgrind's heap profiling, activated by
 153    --profile-heap=no|yes.
 154    The corresponding Free_Fn_t frees the memory chunk p. */
 155
 156 typedef void* (*Alloc_Fn_t)       ( const HChar* cc, SizeT szB );
 157 typedef void  (*Free_Fn_t)        ( void* p );
 158
 159 /* An abstraction of syscall return values.
 160    Linux/MIPS32 and Linux/MIPS64:
 161       When _isError == False,
 162          _val and possible _valEx hold the return value.  Whether
 163          _valEx actually holds a valid value depends on which syscall
 164          this SysRes holds of the result of.
 165       When _isError == True,
 166          _val holds the error code.
 167
 168    Linux/other:
 169       When _isError == False,
 170          _val holds the return value.
 171       When _isError == True,
 172          _val holds the error code.
 173
 174    Darwin:
 175       Interpretation depends on _mode:
 176       MACH, MDEP:
 177          these can never 'fail' (apparently).  The result of the
 178          syscall is a single host word, _wLO.
 179       UNIX:
 180          Can record a double-word error or a double-word result:
 181          When _mode is SysRes_UNIX_OK,  _wHI:_wLO holds the result.
 182          When _mode is SysRes_UNIX_ERR, _wHI:_wLO holds the error code.
 183          Probably the high word of an error is always ignored by
 184          userspace, but we have to record it, so that we can correctly
 185          update both {R,E}DX and {R,E}AX (in guest state) given a SysRes,
 186          if we're required to.
 187
 188    Solaris:
 189       When _isError == False,
 190          _val and _val2 hold the return value.
 191       When _isError == True,
 192          _val holds the error code.
 193 */
 194 #if defined(VGP_mips32_linux) || defined(VGP_mips64_linux)
 195 typedef
 196    struct {
 197       Bool  _isError;
 198       RegWord _val;
 199       UWord _valEx;
 200    }
 201    SysRes;
 202
 203 #elif defined(VGO_linux) \
 204       && !defined(VGP_mips32_linux) && !defined(VGP_mips64_linux)
 205 typedef
 206    struct {
 207       Bool  _isError;
 208       UWord _val;
 209    }
 210    SysRes;
 211
 212 #elif defined(VGO_darwin)
 213 typedef
 214    enum {
 215       SysRes_MACH=40,  // MACH, result is _wLO
 216       SysRes_MDEP,     // MDEP, result is _wLO
 217       SysRes_UNIX_OK,  // UNIX, success, result is _wHI:_wLO
 218       SysRes_UNIX_ERR  // UNIX, error,   error  is _wHI:_wLO
 219    }
 220    SysResMode;
 221 typedef
 222    struct {
 223       UWord _wLO;
 224       UWord _wHI;
 225       SysResMode _mode;
 226    }
 227    SysRes;
 228
 229 #elif defined(VGO_solaris)
 230 typedef
 231    struct {
 232       UWord _val;
 233       UWord _val2;
 234       Bool  _isError;
 235    }
 236    SysRes;
 237
 238 #else
 239 #  error "Unknown OS"
 240 #endif
 241
 242
 243 /* ---- And now some basic accessor functions for it. ---- */
 244
 245 #if defined(VGP_mips32_linux) || defined(VGP_mips64_linux)
 246
 247 static inline Bool sr_isError ( SysRes sr ) {
 248    return sr._isError;
 249 }
 250 static inline RegWord sr_Res ( SysRes sr ) {
 251    return sr._isError ? 0 : sr._val;
 252 }
 253 static inline UWord sr_ResEx ( SysRes sr ) {
 254    return sr._isError ? 0 : sr._valEx;
 255 }
 256 static inline UWord sr_Err ( SysRes sr ) {
 257    return sr._isError ? sr._val : 0;
 258 }
 259 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 260    /* This uglyness of hardcoding syscall numbers is necessary to
 261       avoid having this header file be dependent on
 262       include/vki/vki-scnums-mips{32,64}-linux.h.  It seems pretty
 263       safe given that it is inconceivable that the syscall numbers
 264       for such simple syscalls would ever change.  To make it
 265       really safe, coregrind/m_vkiscnums.c static-asserts that these
 266       syscall numbers haven't changed, so that the build wil simply
 267       fail if they ever do. */
 268 #  if defined(VGP_mips32_linux)
 269    const UInt __nr_Linux = 4000;
 270    const UInt __nr_pipe  = __nr_Linux + 42;
 271    const UInt __nr_pipe2 = __nr_Linux + 328;
 272 #  elif defined(VGP_mips64_linux) && defined(VGABI_N32)
 273    const UInt __nr_Linux = 6000;
 274    const UInt __nr_pipe  = __nr_Linux + 21;
 275    const UInt __nr_pipe2 = __nr_Linux + 291;
 276 #  else
 277    const UInt __nr_Linux = 5000;
 278    const UInt __nr_pipe  = __nr_Linux + 21;
 279    const UInt __nr_pipe2 = __nr_Linux + 287;
 280 #  endif
 281    Bool useEx = sysno == __nr_pipe || sysno == __nr_pipe2;
 282    return sr1._val == sr2._val
 283           && (useEx ? (sr1._valEx == sr2._valEx) : True)
 284           && sr1._isError == sr2._isError;
 285 }
 286
 287 #elif defined(VGO_linux) \
 288       && !defined(VGP_mips32_linux) && !defined(VGP_mips64_linux)
 289
 290 static inline Bool sr_isError ( SysRes sr ) {
 291    return sr._isError;
 292 }
 293 static inline UWord sr_Res ( SysRes sr ) {
 294    return sr._isError ? 0 : sr._val;
 295 }
 296 static inline UWord sr_Err ( SysRes sr ) {
 297 #if defined(VGP_nanomips_linux)
 298    return sr._isError ? -sr._val : 0;
 299 #else
 300    return sr._isError ? sr._val : 0;
 301 #endif
 302 }
 303 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 304    /* sysno is ignored for Linux/not-MIPS */
 305    return sr1._val == sr2._val
 306           && sr1._isError == sr2._isError;
 307 }
 308
 309 #elif defined(VGO_darwin)
 310
 311 static inline Bool sr_isError ( SysRes sr ) {
 312    switch (sr._mode) {
 313       case SysRes_UNIX_ERR:
 314          return True;
 315       /* should check tags properly and assert here, but we can't here */
 316       case SysRes_MACH:
 317       case SysRes_MDEP:
 318       case SysRes_UNIX_OK:
 319       default:
 320          return False;
 321    }
 322 }
 323
 324 static inline UWord sr_Res ( SysRes sr ) {
 325    switch (sr._mode) {
 326       case SysRes_MACH:
 327       case SysRes_MDEP:
 328       case SysRes_UNIX_OK:
 329          return sr._wLO;
 330       /* should assert, but we can't here */
 331       case SysRes_UNIX_ERR:
 332       default:
 333          return 0;
 334    }
 335 }
 336
 337 static inline UWord sr_ResHI ( SysRes sr ) {
 338    switch (sr._mode) {
 339       case SysRes_UNIX_OK:
 340          return sr._wHI;
 341       /* should assert, but we can't here */
 342       case SysRes_MACH:
 343       case SysRes_MDEP:
 344       case SysRes_UNIX_ERR:
 345       default:
 346          return 0;
 347    }
 348 }
 349
 350 static inline UWord sr_Err ( SysRes sr ) {
 351    switch (sr._mode) {
 352       case SysRes_UNIX_ERR:
 353          return sr._wLO;
 354       /* should assert, but we can't here */
 355       case SysRes_MACH:
 356       case SysRes_MDEP:
 357       case SysRes_UNIX_OK:
 358       default:
 359          return 0;
 360    }
 361 }
 362
 363 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 364    /* sysno is ignored for Darwin */
 365    return sr1._mode == sr2._mode
 366           && sr1._wLO == sr2._wLO && sr1._wHI == sr2._wHI;
 367 }
 368
 369 #elif defined(VGO_solaris)
 370
 371 static inline Bool sr_isError ( SysRes sr ) {
 372    return sr._isError;
 373 }
 374 static inline UWord sr_Res ( SysRes sr ) {
 375    return sr._isError ? 0 : sr._val;
 376 }
 377 static inline UWord sr_ResHI ( SysRes sr ) {
 378    return sr._isError ? 0 : sr._val2;
 379 }
 380 static inline UWord sr_Err ( SysRes sr ) {
 381    return sr._isError ? sr._val : 0;
 382 }
 383 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
 384    /* sysno is ignored for Solaris */
 385    return sr1._val == sr2._val
 386        && sr1._isError == sr2._isError
 387        && (!sr1._isError) ? (sr1._val2 == sr2._val2) : True;
 388 }
 389
 390 #else
 391 #  error "Unknown OS"
 392 #endif
 393
 394
 395 /* ---------------------------------------------------------------------
 396    Miscellaneous (word size, endianness, regparmness, stringification)
 397    ------------------------------------------------------------------ */
 398
 399 /* Word size: this is going to be either 4 or 8. */
 400 // It should probably be in m_machine.
 401 #define VG_WORDSIZE VEX_HOST_WORDSIZE
 402
 403 /* Endianness */
 404 #undef VG_BIGENDIAN
 405 #undef VG_LITTLEENDIAN
 406
 407 #if defined(VGA_x86) || defined(VGA_amd64) || defined (VGA_arm) \
 408     || ((defined(VGA_mips32) || defined(VGA_mips64) || defined(VGA_nanomips)) \
 409     && defined (_MIPSEL)) || defined(VGA_arm64)  || defined(VGA_ppc64le)
 410 #  define VG_LITTLEENDIAN 1
 411 #elif defined(VGA_ppc32) || defined(VGA_ppc64be) || defined(VGA_s390x) \
 412       || ((defined(VGA_mips32) || defined(VGA_mips64) || defined(VGA_nanomips)) \
 413       && defined (_MIPSEB))
 414 #  define VG_BIGENDIAN 1
 415 #else
 416 #  error Unknown arch
 417 #endif
 418
 419 /* Offsetof */
 420 #if !defined(offsetof)
 421 #   define offsetof(type,memb) ((SizeT)(HWord)&((type*)0)->memb)
 422 #endif
 423
 424 #if !defined(container_of)
 425 #   define container_of(ptr, type, member) ((type *)((char *)(ptr) - offsetof(type, member)))
 426 #endif
 427
 428 /* Alignment */
 429 /* We use a prefix vg_ for vg_alignof as its behaviour slightly
 430    differs from the standard alignof/gcc defined __alignof__
 431
 432    vg_alignof returns a "safe" alignement.
 433    "safe" is defined as the alignment chosen by the compiler in
 434    a struct made of a char followed by this type.
 435
 436       Note that this is not necessarily the "preferred" alignment
 437       for a platform. This preferred alignment is returned by the gcc
 438        __alignof__ and by the standard (in recent standard) alignof.
 439       Compared to __alignof__, vg_alignof gives on some platforms (e.g.
 440       amd64, ppc32, ppc64) a bigger alignment for long double (16 bytes
 441       instead of 8).
 442       On some platforms (e.g. x86), vg_alignof gives a smaller alignment
 443       than __alignof__ for long long and double (4 bytes instead of 8).
 444       If we want to have the "preferred" alignment for the basic types,
 445       then either we need to depend on gcc __alignof__, or on a (too)
 446       recent standard and compiler (implementing <stdalign.h>).
 447 */
 448 #define vg_alignof(_type) (sizeof(struct {char c;_type _t;})-sizeof(_type))
 449
 450 /* Regparmness */
 451 #if defined(VGA_x86)
 452 #  define VG_REGPARM(n)            __attribute__((regparm(n)))
 453 #elif defined(VGA_amd64) || defined(VGA_ppc32) \
 454       || defined(VGA_ppc64be) || defined(VGA_ppc64le) \
 455       || defined(VGA_arm) || defined(VGA_s390x) \
 456       || defined(VGA_mips32) || defined(VGA_mips64) \
 457       || defined(VGA_arm64) || defined(VGA_nanomips)
 458 #  define VG_REGPARM(n)            /* */
 459 #else
 460 #  error Unknown arch
 461 #endif
 462
 463 /* Macro games */
 464 #define VG_STRINGIFZ(__str)  #__str
 465 #define VG_STRINGIFY(__str)  VG_STRINGIFZ(__str)
 466
 467 // Where to send bug reports to.
 468 #define VG_BUGS_TO "www.valgrind.org"
 469
 470 /* Branch prediction hints. */
 471 #if defined(__GNUC__)
 472 #  define LIKELY(x)   __builtin_expect(!!(x), 1)
 473 #  define UNLIKELY(x) __builtin_expect(!!(x), 0)
 474 #else
 475 #  define LIKELY(x)   (x)
 476 #  define UNLIKELY(x) (x)
 477 #endif
 478
 479 // printf format string checking for gcc.
 480 // This feature has been supported since at least gcc version 2.95.
 481 // For more information about the format attribute, see
 482 // http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Function-Attributes.html.
 483 #if defined(__GNUC__)
 484 #define PRINTF_CHECK(x, y) __attribute__((format(__printf__, x, y)))
 485 #else
 486 #define PRINTF_CHECK(x, y)
 487 #endif
 488
 489 // Macro to "cast" away constness (from type const T to type T) without
 490 // GCC complaining about it. This macro should be used RARELY.
 491 // x is expected to have type const T
 492 #define CONST_CAST(T,x)    \
 493    ({                      \
 494       union {              \
 495          const T in;      \
 496          T out;           \
 497       } var = { .in = x }; var.out;  \
 498    })
 499
 500 /* Some architectures (eg. mips, arm) do not support unaligned memory access
 501    by hardware, so GCC warns about suspicious situations. This macro could
 502    be used to avoid these warnings but only after careful examination. */
 503 #define ASSUME_ALIGNED(D, x)                 \
 504    ({                                        \
 505       union {                                \
 506          void *in;                           \
 507          D out;                              \
 508       } var;                                 \
 509       var.in = (void *) (x); var.out;        \
 510    })
 511
 512 // Poor man's static assert
 513 #define STATIC_ASSERT(x)  extern int VG_(VG_(VG_(unused)))[(x) ? 1 : -1] \
 514                                      __attribute__((unused))
 515
 516 #define VG_MAX(a,b) ((a) > (b) ? a : b)
 517 #define VG_MIN(a,b) ((a) < (b) ? a : b)
 518
 519 #endif /* __PUB_TOOL_BASICS_H */
 520
 521 /*--------------------------------------------------------------------*/
 522 /*--- end                                                          ---*/
 523 /*--------------------------------------------------------------------*/