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-2013 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, write to the Free Software
  25    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  26    02111-1307, USA.
  27
  28    The GNU General Public License is contained in the file COPYING.
  29 */
  30
  31 #ifndef __PUB_TOOL_BASICS_H
  32 #define __PUB_TOOL_BASICS_H
  33
  34 //--------------------------------------------------------------------
  35 // PURPOSE: This header should be imported by every single C file in
  36 // tools.  It contains the basic types and other things needed everywhere.
  37 // There is no corresponding C file because this isn't a module
  38 // containing executable code, it's all just declarations.
  39 //--------------------------------------------------------------------
  40
  41 /* ---------------------------------------------------------------------
  42    Other headers to include
  43    ------------------------------------------------------------------ */
  44
  45 // VEX defines Char, UChar, Short, UShort, Int, UInt, Long, ULong, SizeT,
  46 // Addr, Addr32, Addr64, HWord, HChar, Bool, False and True.
  47 #include "libvex_basictypes.h"
  48
  49 // For varargs types
  50 #include <stdarg.h>
  51
  52
  53 /* ---------------------------------------------------------------------
  54    symbol prefixing
  55    ------------------------------------------------------------------ */
  56
  57 // All symbols externally visible from Valgrind are prefixed
  58 // as specified here to avoid namespace conflict problems.
  59 //
  60 // VG_ is for symbols exported from modules.  ML_ (module-local) is
  61 // for symbols which are not intended to be visible outside modules,
  62 // but which cannot be declared as C 'static's since they need to be
  63 // visible across C files within a given module.  It is a mistake for
  64 // a ML_ name to appear in a pub_core_*.h or pub_tool_*.h file.
  65 // Likewise it is a mistake for a VG_ name to appear in a priv_*.h
  66 // file.
  67
  68 #define VGAPPEND(str1,str2) str1##str2
  69
  70 #define VG_(str)    VGAPPEND(vgPlain_,          str)
  71 #define ML_(str)    VGAPPEND(vgModuleLocal_,    str)
  72
  73
  74 /* ---------------------------------------------------------------------
  75    builtin types
  76    ------------------------------------------------------------------ */
  77
  78 // By choosing the right types, we can get these right for 32-bit and 64-bit
  79 // platforms without having to do any conditional compilation or anything.
  80 // POSIX references:
  81 // - http://www.opengroup.org/onlinepubs/009695399/basedefs/sys/types.h.html
  82 // - http://www.opengroup.org/onlinepubs/009695399/basedefs/stddef.h.html
  83 //
  84 // Size in bits on:                          32-bit archs   64-bit archs
  85 //                                           ------------   ------------
  86 typedef unsigned long          UWord;     // 32             64
  87 typedef   signed long           Word;     // 32             64
  88
  89 // Our equivalent of POSIX 'ssize_t':
  90 // - ssize_t is "used for a count of bytes or an error indication".
  91 typedef  Word                 SSizeT;     // 32             64
  92
  93 // Our equivalent of POSIX 'ptrdiff_t':
  94 // - ptrdiff_t is a "signed integer type of the result of subtracting two
  95 //   pointers".
  96 // We use it for memory offsets, eg. the offset into a memory block.
  97 typedef  Word                 PtrdiffT;   // 32             64
  98
  99 // Our equivalent of POSIX 'off_t':
 100 // - off_t is "used for file sizes".
 101 // At one point we were using it for memory offsets, but PtrdiffT should be
 102 // used in those cases.
 103 // Nb: on Linux, off_t is a signed word-sized int.  On Darwin it's
 104 // always a signed 64-bit int.  So we defined our own Off64T as well.
 105 #if defined(VGO_linux)
 106 typedef Word                   OffT;      // 32             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 /* An abstraction of syscall return values.
 133    Linux:
 134       When _isError == False,
 135          _val holds the return value.
 136       When _isError == True,
 137          _err holds the error code.
 138
 139    Darwin:
 140       Interpretation depends on _mode:
 141       MACH, MDEP:
 142          these can never 'fail' (apparently).  The result of the
 143          syscall is a single host word, _wLO.
 144       UNIX:
 145          Can record a double-word error or a double-word result:
 146          When _mode is SysRes_UNIX_OK,  _wHI:_wLO holds the result.
 147          When _mode is SysRes_UNIX_ERR, _wHI:_wLO holds the error code.
 148          Probably the high word of an error is always ignored by
 149          userspace, but we have to record it, so that we can correctly
 150          update both {R,E}DX and {R,E}AX (in guest state) given a SysRes,
 151          if we're required to.
 152 */
 153 #if defined(VGO_linux)
 154 typedef
 155    struct {
 156       Bool  _isError;
 157       UWord _val;
 158 #if defined(VGA_mips64) || defined(VGA_mips32)
 159       UWord _valEx;
 160 #endif
 161    }
 162    SysRes;
 163 #elif defined(VGO_darwin)
 164 typedef
 165    enum {
 166       SysRes_MACH=40,  // MACH, result is _wLO
 167       SysRes_MDEP,     // MDEP, result is _wLO
 168       SysRes_UNIX_OK,  // UNIX, success, result is _wHI:_wLO
 169       SysRes_UNIX_ERR  // UNIX, error,   error  is _wHI:_wLO
 170    }
 171    SysResMode;
 172 typedef
 173    struct {
 174       UWord _wLO;
 175       UWord _wHI;
 176       SysResMode _mode;
 177    }
 178    SysRes;
 179 #else
 180 #  error "Unknown OS"
 181 #endif
 182
 183
 184 /* ---- And now some basic accessor functions for it. ---- */
 185
 186 #if defined(VGO_linux)
 187
 188 static inline Bool sr_isError ( SysRes sr ) {
 189    return sr._isError;
 190 }
 191 static inline UWord sr_Res ( SysRes sr ) {
 192    return sr._isError ? 0 : sr._val;
 193 }
 194 #if defined(VGA_mips64) || defined(VGA_mips32)
 195 static inline UWord sr_ResEx ( SysRes sr ) {
 196    return sr._isError ? 0 : sr._valEx;
 197 }
 198 #endif
 199 static inline UWord sr_Err ( SysRes sr ) {
 200    return sr._isError ? sr._val : 0;
 201 }
 202 // FIXME: this function needs to be fixed for MIPS
 203 static inline Bool sr_EQ ( SysRes sr1, SysRes sr2 ) {
 204    return sr1._val == sr2._val
 205        && sr1._isError == sr2._isError;
 206 }
 207
 208 #elif defined(VGO_darwin)
 209
 210 static inline Bool sr_isError ( SysRes sr ) {
 211    switch (sr._mode) {
 212       case SysRes_UNIX_ERR:
 213          return True;
 214       /* should check tags properly and assert here, but we can't here */
 215       case SysRes_MACH:
 216       case SysRes_MDEP:
 217       case SysRes_UNIX_OK:
 218       default:
 219          return False;
 220    }
 221 }
 222
 223 static inline UWord sr_Res ( SysRes sr ) {
 224    switch (sr._mode) {
 225       case SysRes_MACH:
 226       case SysRes_MDEP:
 227       case SysRes_UNIX_OK:
 228          return sr._wLO;
 229       /* should assert, but we can't here */
 230       case SysRes_UNIX_ERR:
 231       default:
 232          return 0;
 233    }
 234 }
 235
 236 static inline UWord sr_ResHI ( SysRes sr ) {
 237    switch (sr._mode) {
 238       case SysRes_UNIX_OK:
 239          return sr._wHI;
 240       /* should assert, but we can't here */
 241       case SysRes_MACH:
 242       case SysRes_MDEP:
 243       case SysRes_UNIX_ERR:
 244       default:
 245          return 0;
 246    }
 247 }
 248
 249 static inline UWord sr_Err ( SysRes sr ) {
 250    switch (sr._mode) {
 251       case SysRes_UNIX_ERR:
 252          return sr._wLO;
 253       /* should assert, but we can't here */
 254       case SysRes_MACH:
 255       case SysRes_MDEP:
 256       case SysRes_UNIX_OK:
 257       default:
 258          return 0;
 259    }
 260 }
 261
 262 static inline Bool sr_EQ ( SysRes sr1, SysRes sr2 ) {
 263    return sr1._mode == sr2._mode
 264           && sr1._wLO == sr2._wLO && sr1._wHI == sr2._wHI;
 265 }
 266
 267 #else
 268 #  error "Unknown OS"
 269 #endif
 270
 271
 272 /* ---------------------------------------------------------------------
 273    Miscellaneous (word size, endianness, regparmness, stringification)
 274    ------------------------------------------------------------------ */
 275
 276 /* Word size: this is going to be either 4 or 8. */
 277 // It should probably be in m_machine.
 278 #define VG_WORDSIZE VEX_HOST_WORDSIZE
 279
 280 /* Endianness */
 281 #undef VG_BIGENDIAN
 282 #undef VG_LITTLEENDIAN
 283
 284 #if defined(VGA_x86) || defined(VGA_amd64) || defined (VGA_arm) \
 285     || ((defined(VGA_mips32) || defined(VGA_mips64)) && defined (_MIPSEL)) \
 286     || defined(VGA_arm64)  || defined(VGA_ppc64le) || defined(VGA_tilegx)
 287 #  define VG_LITTLEENDIAN 1
 288 #elif defined(VGA_ppc32) || defined(VGA_ppc64be) || defined(VGA_s390x) \
 289       || ((defined(VGA_mips32) || defined(VGA_mips64)) && defined (_MIPSEB))
 290 #  define VG_BIGENDIAN 1
 291 #else
 292 #  error Unknown arch
 293 #endif
 294
 295 /* Offsetof */
 296 #if !defined(offsetof)
 297 #   define offsetof(type,memb) ((SizeT)(HWord)&((type*)0)->memb)
 298 #endif
 299
 300 /* Alignment */
 301 /* We use a prefix vg_ for vg_alignof as its behaviour slightly
 302    differs from the standard alignof/gcc defined __alignof__
 303
 304    vg_alignof returns a "safe" alignement.
 305    "safe" is defined as the alignment chosen by the compiler in
 306    a struct made of a char followed by this type.
 307
 308       Note that this is not necessarily the "preferred" alignment
 309       for a platform. This preferred alignment is returned by the gcc
 310        __alignof__ and by the standard (in recent standard) alignof.
 311       Compared to __alignof__, vg_alignof gives on some platforms (e.g.
 312       amd64, ppc32, ppc64) a bigger alignment for long double (16 bytes
 313       instead of 8).
 314       On some platforms (e.g. x86), vg_alignof gives a smaller alignment
 315       than __alignof__ for long long and double (4 bytes instead of 8).
 316       If we want to have the "preferred" alignment for the basic types,
 317       then either we need to depend on gcc __alignof__, or on a (too)
 318       recent standard and compiler (implementing <stdalign.h>).
 319 */
 320 #define vg_alignof(_type) (sizeof(struct {char c;_type _t;})-sizeof(_type))
 321
 322 /* Regparmness */
 323 #if defined(VGA_x86)
 324 #  define VG_REGPARM(n)            __attribute__((regparm(n)))
 325 #elif defined(VGA_amd64) || defined(VGA_ppc32) \
 326       || defined(VGA_ppc64be) || defined(VGA_ppc64le) \
 327       || defined(VGA_arm) || defined(VGA_s390x) \
 328       || defined(VGA_mips32) || defined(VGA_mips64) \
 329       || defined(VGA_arm64) || defined(VGA_tilegx)
 330 #  define VG_REGPARM(n)            /* */
 331 #else
 332 #  error Unknown arch
 333 #endif
 334
 335 /* Macro games */
 336 #define VG_STRINGIFZ(__str)  #__str
 337 #define VG_STRINGIFY(__str)  VG_STRINGIFZ(__str)
 338
 339 // Where to send bug reports to.
 340 #define VG_BUGS_TO "www.valgrind.org"
 341
 342 /* Branch prediction hints. */
 343 #if defined(__GNUC__)
 344 #  define LIKELY(x)   __builtin_expect(!!(x), 1)
 345 #  define UNLIKELY(x) __builtin_expect(!!(x), 0)
 346 #else
 347 #  define LIKELY(x)   (x)
 348 #  define UNLIKELY(x) (x)
 349 #endif
 350
 351 // printf format string checking for gcc.
 352 // This feature has been supported since at least gcc version 2.95.
 353 // For more information about the format attribute, see
 354 // http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Function-Attributes.html.
 355 #if defined(__GNUC__)
 356 #define PRINTF_CHECK(x, y) __attribute__((format(__printf__, x, y)))
 357 #else
 358 #define PRINTF_CHECK(x, y)
 359 #endif
 360
 361 // Macro to "cast" away constness (from type const T to type T) without
 362 // GCC complaining about it. This macro should be used RARELY.
 363 // x is expected to have type const T
 364 #define CONST_CAST(T,x)    \
 365    ({                      \
 366       union {              \
 367          const T in;      \
 368          T out;           \
 369       } var = { .in = x }; var.out;  \
 370    })
 371
 372 // Poor man's static assert
 373 #define STATIC_ASSERT(x)  extern int VG_(VG_(VG_(unused)))[(x) ? 1 : -1] \
 374                                      __attribute__((unused))
 375
 376 #endif /* __PUB_TOOL_BASICS_H */
 377
 378 /*--------------------------------------------------------------------*/
 379 /*--- end                                                          ---*/
 380 /*--------------------------------------------------------------------*/