include/valgrind/pub_tool_basics.h

0001
0002 /*--------------------------------------------------------------------*/
0003 /*--- Header included by every tool C file.      pub_tool_basics.h ---*/
0004 /*--------------------------------------------------------------------*/
0005
0006 /*
0007    This file is part of Valgrind, a dynamic binary instrumentation
0008    framework.
0009
0010    Copyright (C) 2000-2017 Julian Seward
0011       jseward@acm.org
0012
0013    This program is free software; you can redistribute it and/or
0014    modify it under the terms of the GNU General Public License as
0015    published by the Free Software Foundation; either version 2 of the
0016    License, or (at your option) any later version.
0017
0018    This program is distributed in the hope that it will be useful, but
0019    WITHOUT ANY WARRANTY; without even the implied warranty of
0020    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0021    General Public License for more details.
0022
0023    You should have received a copy of the GNU General Public License
0024    along with this program; if not, see <http://www.gnu.org/licenses/>.
0025
0026    The GNU General Public License is contained in the file COPYING.
0027 */
0028
0029 #ifndef __PUB_TOOL_BASICS_H
0030 #define __PUB_TOOL_BASICS_H
0031
0032 //--------------------------------------------------------------------
0033 // PURPOSE: This header should be imported by every single C file in
0034 // tools.  It contains the basic types and other things needed everywhere.
0035 // There is no corresponding C file because this isn't a module
0036 // containing executable code, it's all just declarations.
0037 //--------------------------------------------------------------------
0038
0039 /* ---------------------------------------------------------------------
0040    Other headers to include
0041    ------------------------------------------------------------------ */
0042
0043 // VEX defines Char, UChar, Short, UShort, Int, UInt, Long, ULong, SizeT,
0044 // Addr, Addr32, Addr64, HWord, HChar, Bool, False and True.
0045 #include "libvex_basictypes.h"
0046
0047 // For varargs types
0048 #include <stdarg.h>
0049
0050
0051 /* ---------------------------------------------------------------------
0052    symbol prefixing
0053    ------------------------------------------------------------------ */
0054
0055 // All symbols externally visible from Valgrind are prefixed
0056 // as specified here to avoid namespace conflict problems.
0057 //
0058 // VG_ is for symbols exported from modules.  ML_ (module-local) is
0059 // for symbols which are not intended to be visible outside modules,
0060 // but which cannot be declared as C 'static's since they need to be
0061 // visible across C files within a given module.  It is a mistake for
0062 // a ML_ name to appear in a pub_core_*.h or pub_tool_*.h file.
0063 // Likewise it is a mistake for a VG_ name to appear in a priv_*.h
0064 // file.
0065
0066 #define VGAPPEND(str1,str2) str1##str2
0067
0068 #define VG_(str)    VGAPPEND(vgPlain_,          str)
0069 #define ML_(str)    VGAPPEND(vgModuleLocal_,    str)
0070
0071
0072 /* ---------------------------------------------------------------------
0073    builtin types
0074    ------------------------------------------------------------------ */
0075
0076 // By choosing the right types, we can get these right for 32-bit and 64-bit
0077 // platforms without having to do any conditional compilation or anything.
0078 // POSIX references:
0079 // - http://www.opengroup.org/onlinepubs/009695399/basedefs/sys/types.h.html
0080 // - http://www.opengroup.org/onlinepubs/009695399/basedefs/stddef.h.html
0081 //
0082 // Size in bits on:                          32-bit archs   64-bit archs
0083 //                                           ------------   ------------
0084 typedef unsigned long          UWord;     // 32             64
0085 typedef   signed long           Word;     // 32             64
0086
0087 // Our equivalent of POSIX 'ssize_t':
0088 // - ssize_t is "used for a count of bytes or an error indication".
0089 typedef  Word                 SSizeT;     // 32             64
0090
0091 // Our equivalent of POSIX 'ptrdiff_t':
0092 // - ptrdiff_t is a "signed integer type of the result of subtracting two
0093 //   pointers".
0094 // We use it for memory offsets, eg. the offset into a memory block.
0095 typedef  Word                 PtrdiffT;   // 32             64
0096
0097 // Our equivalent of POSIX 'off_t':
0098 // - off_t is "used for file sizes".
0099 // At one point we were using it for memory offsets, but PtrdiffT should be
0100 // used in those cases.
0101 // Nb: on Linux, off_t is a signed word-sized int.  On Darwin it's
0102 // always a signed 64-bit int.  So we defined our own Off64T as well.
0103 #if defined(VGO_linux) || defined(VGO_solaris)
0104 typedef Word                   OffT;      // 32             64
0105 #elif defined(VGO_freebsd)
0106 typedef Long                   OffT;      // 64             64
0107 #elif defined(VGO_darwin)
0108 typedef Long                   OffT;      // 64             64
0109 #else
0110 #  error Unknown OS
0111 #endif
0112 typedef Long                 Off64T;      // 64             64
0113
0114 #if !defined(NULL)
0115 #  define NULL ((void*)0)
0116 #endif
0117
0118 /* This is just too useful to not have around the place somewhere. */
0119 typedef  struct { UWord uw1; UWord uw2; }  UWordPair;
0120
0121
0122 /* ---------------------------------------------------------------------
0123    non-builtin types
0124    ------------------------------------------------------------------ */
0125
0126 // These probably shouldn't be here, but moving them to their logical
0127 // modules results in a lot more #includes...
0128
0129 /* ThreadIds are simply indices into the VG_(threads)[] array. */
0130 typedef UInt ThreadId;
0131
0132
0133 /* You need a debuginfo epoch in order to convert an address into any source
0134    level entity, since that conversion depends on what objects were mapped
0135    in at the time.  An epoch is simply a monotonically increasing counter,
0136    which we wrap up in a struct so as to enable the C type system to
0137    distinguish it from other kinds of numbers.  m_debuginfo holds and
0138    maintains the current epoch number. */
0139 typedef  struct { UInt n; }  DiEpoch;
0140
0141 static inline DiEpoch DiEpoch_INVALID ( void ) {
0142    DiEpoch dep; dep.n = 0; return dep;
0143 }
0144
0145 static inline Bool is_DiEpoch_INVALID ( DiEpoch dep ) {
0146    return dep.n == 0;
0147 }
0148
0149
0150 /* Many data structures need to allocate and release memory.
0151    The allocation/release functions must be provided by the caller.
0152    The Alloc_Fn_t function must allocate a chunk of memory of size szB.
0153    cc is the Cost Centre for this allocated memory. This constant string
0154    is used to provide Valgrind's heap profiling, activated by
0155    --profile-heap=no|yes.
0156    The corresponding Free_Fn_t frees the memory chunk p. */
0157
0158 typedef void* (*Alloc_Fn_t)       ( const HChar* cc, SizeT szB );
0159 typedef void  (*Free_Fn_t)        ( void* p );
0160
0161 /* An abstraction of syscall return values.
0162    Linux/MIPS32 and Linux/MIPS64:
0163       When _isError == False,
0164          _val and possible _valEx hold the return value.  Whether
0165          _valEx actually holds a valid value depends on which syscall
0166          this SysRes holds of the result of.
0167       When _isError == True,
0168          _val holds the error code.
0169
0170    Linux/other:
0171       When _isError == False,
0172          _val holds the return value.
0173       When _isError == True,
0174          _val holds the error code.
0175
0176    Darwin:
0177       Interpretation depends on _mode:
0178       MACH, MDEP:
0179          these can never 'fail' (apparently).  The result of the
0180          syscall is a single host word, _wLO.
0181       UNIX:
0182          Can record a double-word error or a double-word result:
0183          When _mode is SysRes_UNIX_OK,  _wHI:_wLO holds the result.
0184          When _mode is SysRes_UNIX_ERR, _wHI:_wLO holds the error code.
0185          Probably the high word of an error is always ignored by
0186          userspace, but we have to record it, so that we can correctly
0187          update both {R,E}DX and {R,E}AX (in guest state) given a SysRes,
0188          if we're required to.
0189
0190    Solaris:
0191       When _isError == False,
0192          _val and _val2 hold the return value.
0193       When _isError == True,
0194          _val holds the error code.
0195 */
0196 #if defined(VGP_mips32_linux) || defined(VGP_mips64_linux)
0197 typedef
0198    struct {
0199       Bool  _isError;
0200       RegWord _val;
0201       UWord _valEx;
0202    }
0203    SysRes;
0204
0205 #elif defined(VGO_linux) \
0206       && !defined(VGP_mips32_linux) && !defined(VGP_mips64_linux)
0207 typedef
0208    struct {
0209       Bool  _isError;
0210       UWord _val;
0211    }
0212    SysRes;
0213
0214 #elif defined(VGO_darwin)
0215 typedef
0216    enum {
0217       SysRes_MACH=40,  // MACH, result is _wLO
0218       SysRes_MDEP,     // MDEP, result is _wLO
0219       SysRes_UNIX_OK,  // UNIX, success, result is _wHI:_wLO
0220       SysRes_UNIX_ERR  // UNIX, error,   error  is _wHI:_wLO
0221    }
0222    SysResMode;
0223 typedef
0224    struct {
0225       UWord _wLO;
0226       UWord _wHI;
0227       SysResMode _mode;
0228    }
0229    SysRes;
0230 #elif defined(VGO_freebsd)
0231 typedef
0232    struct {
0233       UWord _val;
0234       UWord _val2;
0235       Bool  _isError;
0236 #if defined(VGP_amd64_freebsd)
0237       char  padding[7];
0238 #else
0239       char  padding[3];
0240 #endif
0241    }
0242    SysRes;
0243
0244 #elif defined(VGO_solaris)
0245 typedef
0246    struct {
0247       UWord _val;
0248       UWord _val2;
0249       Bool  _isError;
0250    }
0251    SysRes;
0252
0253 #else
0254 #  error "Unknown OS"
0255 #endif
0256
0257
0258 /* ---- And now some basic accessor functions for it. ---- */
0259
0260 #if defined(VGP_mips32_linux) || defined(VGP_mips64_linux)
0261
0262 static inline Bool sr_isError ( SysRes sr ) {
0263    return sr._isError;
0264 }
0265 static inline RegWord sr_Res ( SysRes sr ) {
0266    return sr._isError ? 0 : sr._val;
0267 }
0268 static inline UWord sr_ResEx ( SysRes sr ) {
0269    return sr._isError ? 0 : sr._valEx;
0270 }
0271 static inline UWord sr_Err ( SysRes sr ) {
0272    return sr._isError ? sr._val : 0;
0273 }
0274 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
0275    /* This uglyness of hardcoding syscall numbers is necessary to
0276       avoid having this header file be dependent on
0277       include/vki/vki-scnums-mips{32,64}-linux.h.  It seems pretty
0278       safe given that it is inconceivable that the syscall numbers
0279       for such simple syscalls would ever change.  To make it
0280       really safe, coregrind/m_vkiscnums.c static-asserts that these
0281       syscall numbers haven't changed, so that the build wil simply
0282       fail if they ever do. */
0283 #  if defined(VGP_mips32_linux)
0284    const UInt __nr_Linux = 4000;
0285    const UInt __nr_pipe  = __nr_Linux + 42;
0286    const UInt __nr_pipe2 = __nr_Linux + 328;
0287 #  elif defined(VGP_mips64_linux) && defined(VGABI_N32)
0288    const UInt __nr_Linux = 6000;
0289    const UInt __nr_pipe  = __nr_Linux + 21;
0290    const UInt __nr_pipe2 = __nr_Linux + 291;
0291 #  else
0292    const UInt __nr_Linux = 5000;
0293    const UInt __nr_pipe  = __nr_Linux + 21;
0294    const UInt __nr_pipe2 = __nr_Linux + 287;
0295 #  endif
0296    Bool useEx = sysno == __nr_pipe || sysno == __nr_pipe2;
0297    return sr1._val == sr2._val
0298           && (useEx ? (sr1._valEx == sr2._valEx) : True)
0299           && sr1._isError == sr2._isError;
0300 }
0301
0302 #elif defined(VGO_linux) \
0303       && !defined(VGP_mips32_linux) && !defined(VGP_mips64_linux)
0304
0305 static inline Bool sr_isError ( SysRes sr ) {
0306    return sr._isError;
0307 }
0308 static inline UWord sr_Res ( SysRes sr ) {
0309    return sr._isError ? 0 : sr._val;
0310 }
0311 static inline UWord sr_Err ( SysRes sr ) {
0312 #if defined(VGP_nanomips_linux)
0313    return sr._isError ? -sr._val : 0;
0314 #else
0315    return sr._isError ? sr._val : 0;
0316 #endif
0317 }
0318 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
0319    /* sysno is ignored for Linux/not-MIPS */
0320    return sr1._val == sr2._val
0321           && sr1._isError == sr2._isError;
0322 }
0323
0324 #elif defined(VGO_freebsd)
0325
0326 static inline Bool sr_isError ( SysRes sr ) {
0327    return sr._isError;
0328 }
0329 static inline UWord sr_Res ( SysRes sr ) {
0330    return sr._isError ? 0 : sr._val;
0331 }
0332 static inline UWord sr_ResHI ( SysRes sr ) {
0333    return sr._isError ? 0 : sr._val2;
0334 }
0335 static inline UWord sr_Err ( SysRes sr ) {
0336    return sr._isError ? sr._val : 0;
0337 }
0338 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
0339    return sr_Res(sr1) == sr_Res(sr2)
0340           && sr_ResHI(sr1) == sr_ResHI(sr2)
0341           && ((sr_isError(sr1) && sr_isError(sr2))
0342               || (!sr_isError(sr1) && !sr_isError(sr2)));
0343 }
0344
0345 #elif defined(VGO_darwin)
0346
0347 static inline Bool sr_isError ( SysRes sr ) {
0348    switch (sr._mode) {
0349       case SysRes_UNIX_ERR:
0350          return True;
0351       /* should check tags properly and assert here, but we can't here */
0352       case SysRes_MACH:
0353       case SysRes_MDEP:
0354       case SysRes_UNIX_OK:
0355       default:
0356          return False;
0357    }
0358 }
0359
0360 static inline UWord sr_Res ( SysRes sr ) {
0361    switch (sr._mode) {
0362       case SysRes_MACH:
0363       case SysRes_MDEP:
0364       case SysRes_UNIX_OK:
0365          return sr._wLO;
0366       /* should assert, but we can't here */
0367       case SysRes_UNIX_ERR:
0368       default:
0369          return 0;
0370    }
0371 }
0372
0373 static inline UWord sr_ResHI ( SysRes sr ) {
0374    switch (sr._mode) {
0375       case SysRes_UNIX_OK:
0376          return sr._wHI;
0377       /* should assert, but we can't here */
0378       case SysRes_MACH:
0379       case SysRes_MDEP:
0380       case SysRes_UNIX_ERR:
0381       default:
0382          return 0;
0383    }
0384 }
0385
0386 static inline UWord sr_Err ( SysRes sr ) {
0387    switch (sr._mode) {
0388       case SysRes_UNIX_ERR:
0389          return sr._wLO;
0390       /* should assert, but we can't here */
0391       case SysRes_MACH:
0392       case SysRes_MDEP:
0393       case SysRes_UNIX_OK:
0394       default:
0395          return 0;
0396    }
0397 }
0398
0399 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
0400    /* sysno is ignored for Darwin */
0401    return sr1._mode == sr2._mode
0402           && sr1._wLO == sr2._wLO && sr1._wHI == sr2._wHI;
0403 }
0404
0405 #elif defined(VGO_solaris)
0406
0407 static inline Bool sr_isError ( SysRes sr ) {
0408    return sr._isError;
0409 }
0410 static inline UWord sr_Res ( SysRes sr ) {
0411    return sr._isError ? 0 : sr._val;
0412 }
0413 static inline UWord sr_ResHI ( SysRes sr ) {
0414    return sr._isError ? 0 : sr._val2;
0415 }
0416 static inline UWord sr_Err ( SysRes sr ) {
0417    return sr._isError ? sr._val : 0;
0418 }
0419 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
0420    /* sysno is ignored for Solaris */
0421    return sr1._val == sr2._val
0422        && sr1._isError == sr2._isError
0423        && (!sr1._isError) ? (sr1._val2 == sr2._val2) : True;
0424 }
0425
0426 #else
0427 #  error "Unknown OS"
0428 #endif
0429
0430
0431 /* ---------------------------------------------------------------------
0432    Miscellaneous (word size, endianness, regparmness, stringification)
0433    ------------------------------------------------------------------ */
0434
0435 /* Word size: this is going to be either 4 or 8. */
0436 // It should probably be in m_machine.
0437 #define VG_WORDSIZE VEX_HOST_WORDSIZE
0438
0439 /* Endianness */
0440 #undef VG_BIGENDIAN
0441 #undef VG_LITTLEENDIAN
0442
0443 #if defined(VGA_x86) || defined(VGA_amd64) || defined (VGA_arm) \
0444     || ((defined(VGA_mips32) || defined(VGA_mips64) || defined(VGA_nanomips)) \
0445     && defined (_MIPSEL)) || defined(VGA_arm64)  || defined(VGA_ppc64le)
0446 #  define VG_LITTLEENDIAN 1
0447 #elif defined(VGA_ppc32) || defined(VGA_ppc64be) || defined(VGA_s390x) \
0448       || ((defined(VGA_mips32) || defined(VGA_mips64) || defined(VGA_nanomips)) \
0449       && defined (_MIPSEB))
0450 #  define VG_BIGENDIAN 1
0451 #else
0452 #  error Unknown arch
0453 #endif
0454
0455 /* Offsetof */
0456 #if !defined(offsetof)
0457 #   define offsetof(type,memb) ((SizeT)(HWord)&((type*)0)->memb)
0458 #endif
0459
0460 #if !defined(container_of)
0461 #   define container_of(ptr, type, member) ((type *)((char *)(ptr) - offsetof(type, member)))
0462 #endif
0463
0464 /* Alignment */
0465 /* We use a prefix vg_ for vg_alignof as its behaviour slightly
0466    differs from the standard alignof/gcc defined __alignof__
0467
0468    vg_alignof returns a "safe" alignement.
0469    "safe" is defined as the alignment chosen by the compiler in
0470    a struct made of a char followed by this type.
0471
0472       Note that this is not necessarily the "preferred" alignment
0473       for a platform. This preferred alignment is returned by the gcc
0474        __alignof__ and by the standard (in recent standard) alignof.
0475       Compared to __alignof__, vg_alignof gives on some platforms (e.g.
0476       amd64, ppc32, ppc64) a bigger alignment for long double (16 bytes
0477       instead of 8).
0478       On some platforms (e.g. x86), vg_alignof gives a smaller alignment
0479       than __alignof__ for long long and double (4 bytes instead of 8).
0480       If we want to have the "preferred" alignment for the basic types,
0481       then either we need to depend on gcc __alignof__, or on a (too)
0482       recent standard and compiler (implementing <stdalign.h>).
0483 */
0484 #define vg_alignof(_type) (sizeof(struct {char c;_type _t;})-sizeof(_type))
0485
0486 /* Regparmness */
0487 #if defined(VGA_x86)
0488 #  define VG_REGPARM(n)            __attribute__((regparm(n)))
0489 #elif defined(VGA_amd64) || defined(VGA_ppc32) \
0490       || defined(VGA_ppc64be) || defined(VGA_ppc64le) \
0491       || defined(VGA_arm) || defined(VGA_s390x) \
0492       || defined(VGA_mips32) || defined(VGA_mips64) \
0493       || defined(VGA_arm64) || defined(VGA_nanomips)
0494 #  define VG_REGPARM(n)            /* */
0495 #else
0496 #  error Unknown arch
0497 #endif
0498
0499 /* Macro games */
0500 #define VG_STRINGIFZ(__str)  #__str
0501 #define VG_STRINGIFY(__str)  VG_STRINGIFZ(__str)
0502
0503 // Where to send bug reports to.
0504 #define VG_BUGS_TO "www.valgrind.org"
0505
0506 /* Branch prediction hints. */
0507 #if defined(__GNUC__)
0508 #  define LIKELY(x)   __builtin_expect(!!(x), 1)
0509 #  define UNLIKELY(x) __builtin_expect(!!(x), 0)
0510 #else
0511 #  define LIKELY(x)   (x)
0512 #  define UNLIKELY(x) (x)
0513 #endif
0514
0515 // printf format string checking for gcc.
0516 // This feature has been supported since at least gcc version 2.95.
0517 // For more information about the format attribute, see
0518 // http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Function-Attributes.html.
0519 #if defined(__GNUC__)
0520 #define PRINTF_CHECK(x, y) __attribute__((format(__printf__, x, y)))
0521 #else
0522 #define PRINTF_CHECK(x, y)
0523 #endif
0524
0525 // Macro to "cast" away constness (from type const T to type T) without
0526 // GCC complaining about it. This macro should be used RARELY.
0527 // x is expected to have type const T
0528 #define CONST_CAST(T,x)    \
0529    ({                      \
0530       union {              \
0531          const T in;      \
0532          T out;           \
0533       } var = { .in = x }; var.out;  \
0534    })
0535
0536 /* Some architectures (eg. mips, arm) do not support unaligned memory access
0537    by hardware, so GCC warns about suspicious situations. This macro could
0538    be used to avoid these warnings but only after careful examination. */
0539 #define ASSUME_ALIGNED(D, x)                 \
0540    ({                                        \
0541       union {                                \
0542          void *in;                           \
0543          D out;                              \
0544       } var;                                 \
0545       var.in = (void *) (x); var.out;        \
0546    })
0547
0548 // Poor man's static assert
0549 #define STATIC_ASSERT(x)  extern int VG_(VG_(VG_(unused)))[(x) ? 1 : -1] \
0550                                      __attribute__((unused))
0551
0552 #define VG_MAX(a,b) ((a) > (b) ? a : b)
0553 #define VG_MIN(a,b) ((a) < (b) ? a : b)
0554
0555 #endif /* __PUB_TOOL_BASICS_H */
0556
0557 /*--------------------------------------------------------------------*/
0558 /*--- end                                                          ---*/
0559 /*--------------------------------------------------------------------*/