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    }
0237    SysRes;
0238
0239 #elif defined(VGO_solaris)
0240 typedef
0241    struct {
0242       UWord _val;
0243       UWord _val2;
0244       Bool  _isError;
0245    }
0246    SysRes;
0247
0248 #else
0249 #  error "Unknown OS"
0250 #endif
0251
0252
0253 /* ---- And now some basic accessor functions for it. ---- */
0254
0255 #if defined(VGP_mips32_linux) || defined(VGP_mips64_linux)
0256
0257 static inline Bool sr_isError ( SysRes sr ) {
0258    return sr._isError;
0259 }
0260 static inline RegWord sr_Res ( SysRes sr ) {
0261    return sr._isError ? 0 : sr._val;
0262 }
0263 static inline UWord sr_ResEx ( SysRes sr ) {
0264    return sr._isError ? 0 : sr._valEx;
0265 }
0266 static inline UWord sr_Err ( SysRes sr ) {
0267    return sr._isError ? sr._val : 0;
0268 }
0269 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
0270    /* This uglyness of hardcoding syscall numbers is necessary to
0271       avoid having this header file be dependent on
0272       include/vki/vki-scnums-mips{32,64}-linux.h.  It seems pretty
0273       safe given that it is inconceivable that the syscall numbers
0274       for such simple syscalls would ever change.  To make it
0275       really safe, coregrind/m_vkiscnums.c static-asserts that these
0276       syscall numbers haven't changed, so that the build wil simply
0277       fail if they ever do. */
0278 #  if defined(VGP_mips32_linux)
0279    const UInt __nr_Linux = 4000;
0280    const UInt __nr_pipe  = __nr_Linux + 42;
0281    const UInt __nr_pipe2 = __nr_Linux + 328;
0282 #  elif defined(VGP_mips64_linux) && defined(VGABI_N32)
0283    const UInt __nr_Linux = 6000;
0284    const UInt __nr_pipe  = __nr_Linux + 21;
0285    const UInt __nr_pipe2 = __nr_Linux + 291;
0286 #  else
0287    const UInt __nr_Linux = 5000;
0288    const UInt __nr_pipe  = __nr_Linux + 21;
0289    const UInt __nr_pipe2 = __nr_Linux + 287;
0290 #  endif
0291    Bool useEx = sysno == __nr_pipe || sysno == __nr_pipe2;
0292    return sr1._val == sr2._val
0293           && (useEx ? (sr1._valEx == sr2._valEx) : True)
0294           && sr1._isError == sr2._isError;
0295 }
0296
0297 #elif defined(VGO_linux) \
0298       && !defined(VGP_mips32_linux) && !defined(VGP_mips64_linux)
0299
0300 static inline Bool sr_isError ( SysRes sr ) {
0301    return sr._isError;
0302 }
0303 static inline UWord sr_Res ( SysRes sr ) {
0304    return sr._isError ? 0 : sr._val;
0305 }
0306 static inline UWord sr_Err ( SysRes sr ) {
0307 #if defined(VGP_nanomips_linux)
0308    return sr._isError ? -sr._val : 0;
0309 #else
0310    return sr._isError ? sr._val : 0;
0311 #endif
0312 }
0313 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
0314    /* sysno is ignored for Linux/not-MIPS */
0315    return sr1._val == sr2._val
0316           && sr1._isError == sr2._isError;
0317 }
0318
0319 #elif defined(VGO_freebsd)
0320
0321 static inline Bool sr_isError ( SysRes sr ) {
0322    return sr._isError;
0323 }
0324 static inline UWord sr_Res ( SysRes sr ) {
0325    return sr._isError ? 0 : sr._val;
0326 }
0327 static inline UWord sr_ResHI ( SysRes sr ) {
0328    return sr._isError ? 0 : sr._val2;
0329 }
0330 static inline UWord sr_Err ( SysRes sr ) {
0331    return sr._isError ? sr._val : 0;
0332 }
0333 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
0334    return sr_Res(sr1) == sr_Res(sr2)
0335           && sr_ResHI(sr1) == sr_ResHI(sr2)
0336           && ((sr_isError(sr1) && sr_isError(sr2))
0337               || (!sr_isError(sr1) && !sr_isError(sr2)));
0338 }
0339
0340 #elif defined(VGO_darwin)
0341
0342 static inline Bool sr_isError ( SysRes sr ) {
0343    switch (sr._mode) {
0344       case SysRes_UNIX_ERR:
0345          return True;
0346       /* should check tags properly and assert here, but we can't here */
0347       case SysRes_MACH:
0348       case SysRes_MDEP:
0349       case SysRes_UNIX_OK:
0350       default:
0351          return False;
0352    }
0353 }
0354
0355 static inline UWord sr_Res ( SysRes sr ) {
0356    switch (sr._mode) {
0357       case SysRes_MACH:
0358       case SysRes_MDEP:
0359       case SysRes_UNIX_OK:
0360          return sr._wLO;
0361       /* should assert, but we can't here */
0362       case SysRes_UNIX_ERR:
0363       default:
0364          return 0;
0365    }
0366 }
0367
0368 static inline UWord sr_ResHI ( SysRes sr ) {
0369    switch (sr._mode) {
0370       case SysRes_UNIX_OK:
0371          return sr._wHI;
0372       /* should assert, but we can't here */
0373       case SysRes_MACH:
0374       case SysRes_MDEP:
0375       case SysRes_UNIX_ERR:
0376       default:
0377          return 0;
0378    }
0379 }
0380
0381 static inline UWord sr_Err ( SysRes sr ) {
0382    switch (sr._mode) {
0383       case SysRes_UNIX_ERR:
0384          return sr._wLO;
0385       /* should assert, but we can't here */
0386       case SysRes_MACH:
0387       case SysRes_MDEP:
0388       case SysRes_UNIX_OK:
0389       default:
0390          return 0;
0391    }
0392 }
0393
0394 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
0395    /* sysno is ignored for Darwin */
0396    return sr1._mode == sr2._mode
0397           && sr1._wLO == sr2._wLO && sr1._wHI == sr2._wHI;
0398 }
0399
0400 #elif defined(VGO_solaris)
0401
0402 static inline Bool sr_isError ( SysRes sr ) {
0403    return sr._isError;
0404 }
0405 static inline UWord sr_Res ( SysRes sr ) {
0406    return sr._isError ? 0 : sr._val;
0407 }
0408 static inline UWord sr_ResHI ( SysRes sr ) {
0409    return sr._isError ? 0 : sr._val2;
0410 }
0411 static inline UWord sr_Err ( SysRes sr ) {
0412    return sr._isError ? sr._val : 0;
0413 }
0414 static inline Bool sr_EQ ( UInt sysno, SysRes sr1, SysRes sr2 ) {
0415    /* sysno is ignored for Solaris */
0416    return sr1._val == sr2._val
0417        && sr1._isError == sr2._isError
0418        && (!sr1._isError) ? (sr1._val2 == sr2._val2) : True;
0419 }
0420
0421 #else
0422 #  error "Unknown OS"
0423 #endif
0424
0425
0426 /* ---------------------------------------------------------------------
0427    Miscellaneous (word size, endianness, regparmness, stringification)
0428    ------------------------------------------------------------------ */
0429
0430 /* Word size: this is going to be either 4 or 8. */
0431 // It should probably be in m_machine.
0432 #define VG_WORDSIZE VEX_HOST_WORDSIZE
0433
0434 /* Endianness */
0435 #undef VG_BIGENDIAN
0436 #undef VG_LITTLEENDIAN
0437
0438 #if defined(VGA_x86) || defined(VGA_amd64) || defined (VGA_arm) \
0439     || ((defined(VGA_mips32) || defined(VGA_mips64) || defined(VGA_nanomips)) \
0440     && defined (_MIPSEL)) || defined(VGA_arm64)  || defined(VGA_ppc64le)
0441 #  define VG_LITTLEENDIAN 1
0442 #elif defined(VGA_ppc32) || defined(VGA_ppc64be) || defined(VGA_s390x) \
0443       || ((defined(VGA_mips32) || defined(VGA_mips64) || defined(VGA_nanomips)) \
0444       && defined (_MIPSEB))
0445 #  define VG_BIGENDIAN 1
0446 #else
0447 #  error Unknown arch
0448 #endif
0449
0450 /* Offsetof */
0451 #if !defined(offsetof)
0452 #   define offsetof(type,memb) ((SizeT)(HWord)&((type*)0)->memb)
0453 #endif
0454
0455 #if !defined(container_of)
0456 #   define container_of(ptr, type, member) ((type *)((char *)(ptr) - offsetof(type, member)))
0457 #endif
0458
0459 /* Alignment */
0460 /* We use a prefix vg_ for vg_alignof as its behaviour slightly
0461    differs from the standard alignof/gcc defined __alignof__
0462
0463    vg_alignof returns a "safe" alignement.
0464    "safe" is defined as the alignment chosen by the compiler in
0465    a struct made of a char followed by this type.
0466
0467       Note that this is not necessarily the "preferred" alignment
0468       for a platform. This preferred alignment is returned by the gcc
0469        __alignof__ and by the standard (in recent standard) alignof.
0470       Compared to __alignof__, vg_alignof gives on some platforms (e.g.
0471       amd64, ppc32, ppc64) a bigger alignment for long double (16 bytes
0472       instead of 8).
0473       On some platforms (e.g. x86), vg_alignof gives a smaller alignment
0474       than __alignof__ for long long and double (4 bytes instead of 8).
0475       If we want to have the "preferred" alignment for the basic types,
0476       then either we need to depend on gcc __alignof__, or on a (too)
0477       recent standard and compiler (implementing <stdalign.h>).
0478 */
0479 #define vg_alignof(_type) (sizeof(struct {char c;_type _t;})-sizeof(_type))
0480
0481 /* Regparmness */
0482 #if defined(VGA_x86)
0483 #  define VG_REGPARM(n)            __attribute__((regparm(n)))
0484 #elif defined(VGA_amd64) || defined(VGA_ppc32) \
0485       || defined(VGA_ppc64be) || defined(VGA_ppc64le) \
0486       || defined(VGA_arm) || defined(VGA_s390x) \
0487       || defined(VGA_mips32) || defined(VGA_mips64) \
0488       || defined(VGA_arm64) || defined(VGA_nanomips)
0489 #  define VG_REGPARM(n)            /* */
0490 #else
0491 #  error Unknown arch
0492 #endif
0493
0494 /* Macro games */
0495 #define VG_STRINGIFZ(__str)  #__str
0496 #define VG_STRINGIFY(__str)  VG_STRINGIFZ(__str)
0497
0498 // Where to send bug reports to.
0499 #define VG_BUGS_TO "www.valgrind.org"
0500
0501 /* Branch prediction hints. */
0502 #if defined(__GNUC__)
0503 #  define LIKELY(x)   __builtin_expect(!!(x), 1)
0504 #  define UNLIKELY(x) __builtin_expect(!!(x), 0)
0505 #else
0506 #  define LIKELY(x)   (x)
0507 #  define UNLIKELY(x) (x)
0508 #endif
0509
0510 // printf format string checking for gcc.
0511 // This feature has been supported since at least gcc version 2.95.
0512 // For more information about the format attribute, see
0513 // http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Function-Attributes.html.
0514 #if defined(__GNUC__)
0515 #define PRINTF_CHECK(x, y) __attribute__((format(__printf__, x, y)))
0516 #else
0517 #define PRINTF_CHECK(x, y)
0518 #endif
0519
0520 // Macro to "cast" away constness (from type const T to type T) without
0521 // GCC complaining about it. This macro should be used RARELY.
0522 // x is expected to have type const T
0523 #define CONST_CAST(T,x)    \
0524    ({                      \
0525       union {              \
0526          const T in;      \
0527          T out;           \
0528       } var = { .in = x }; var.out;  \
0529    })
0530
0531 /* Some architectures (eg. mips, arm) do not support unaligned memory access
0532    by hardware, so GCC warns about suspicious situations. This macro could
0533    be used to avoid these warnings but only after careful examination. */
0534 #define ASSUME_ALIGNED(D, x)                 \
0535    ({                                        \
0536       union {                                \
0537          void *in;                           \
0538          D out;                              \
0539       } var;                                 \
0540       var.in = (void *) (x); var.out;        \
0541    })
0542
0543 // Poor man's static assert
0544 #define STATIC_ASSERT(x)  extern int VG_(VG_(VG_(unused)))[(x) ? 1 : -1] \
0545                                      __attribute__((unused))
0546
0547 #define VG_MAX(a,b) ((a) > (b) ? a : b)
0548 #define VG_MIN(a,b) ((a) < (b) ? a : b)
0549
0550 #endif /* __PUB_TOOL_BASICS_H */
0551
0552 /*--------------------------------------------------------------------*/
0553 /*--- end                                                          ---*/
0554 /*--------------------------------------------------------------------*/