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,
46// 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//                                           ------------   ------------
86typedef unsigned long          UWord;     // 32             64
87typedef   signed long           Word;     // 32             64
88
89// Addr is for holding an address.  AddrH was intended to be "Addr on the
90// host", for the notional case where host word size != guest word size.
91// But since the assumption that host arch == guest arch has become so
92// deeply wired in, it's a pretty pointless distinction now.
93typedef UWord                  Addr;      // 32             64
94typedef UWord                  AddrH;     // 32             64
95
96// Our equivalents of POSIX 'size_t' and 'ssize_t':
97// - size_t is an "unsigned integer type of the result of the sizeof operator".
98// - ssize_t is "used for a count of bytes or an error indication".
99typedef UWord                  SizeT;     // 32             64
100typedef  Word                 SSizeT;     // 32             64
101
102// Our equivalent of POSIX 'ptrdiff_t':
103// - ptrdiff_t is a "signed integer type of the result of subtracting two
104//   pointers".
105// We use it for memory offsets, eg. the offset into a memory block.
106typedef  Word                 PtrdiffT;   // 32             64
107
108// Our equivalent of POSIX 'off_t':
109// - off_t is "used for file sizes".
110// At one point we were using it for memory offsets, but PtrdiffT should be
111// used in those cases.
112// Nb: on Linux, off_t is a signed word-sized int.  On Darwin it's
113// always a signed 64-bit int.  So we defined our own Off64T as well.
114#if defined(VGO_linux)
115typedef Word                   OffT;      // 32             64
116#elif defined(VGO_darwin)
117typedef Long                   OffT;      // 64             64
118#else
119#  error Unknown OS
120#endif
121typedef Long                 Off64T;      // 64             64
122
123#if !defined(NULL)
124#  define NULL ((void*)0)
125#endif
126
127/* This is just too useful to not have around the place somewhere. */
128typedef  struct { UWord uw1; UWord uw2; }  UWordPair;
129
130
131/* ---------------------------------------------------------------------
132   non-builtin types
133   ------------------------------------------------------------------ */
134
135// These probably shouldn't be here, but moving them to their logical
136// modules results in a lot more #includes...
137
138/* ThreadIds are simply indices into the VG_(threads)[] array. */
139typedef UInt ThreadId;
140
141/* An abstraction of syscall return values.
142   Linux:
143      When _isError == False,
144         _val holds the return value.
145      When _isError == True,
146         _err holds the error code.
147
148   Darwin:
149      Interpretation depends on _mode:
150      MACH, MDEP:
151         these can never 'fail' (apparently).  The result of the
152         syscall is a single host word, _wLO.
153      UNIX:
154         Can record a double-word error or a double-word result:
155         When _mode is SysRes_UNIX_OK,  _wHI:_wLO holds the result.
156         When _mode is SysRes_UNIX_ERR, _wHI:_wLO holds the error code.
157         Probably the high word of an error is always ignored by
158         userspace, but we have to record it, so that we can correctly
159         update both {R,E}DX and {R,E}AX (in guest state) given a SysRes,
160         if we're required to.
161*/
162#if defined(VGO_linux)
163typedef
164   struct {
165      UWord _val;
166      UWord _valEx;   // only used on mips-linux
167      Bool  _isError;
168   }
169   SysRes;
170#elif defined(VGO_darwin)
171typedef
172   enum {
173      SysRes_MACH=40,  // MACH, result is _wLO
174      SysRes_MDEP,     // MDEP, result is _wLO
175      SysRes_UNIX_OK,  // UNIX, success, result is _wHI:_wLO
176      SysRes_UNIX_ERR  // UNIX, error,   error  is _wHI:_wLO
177   }
178   SysResMode;
179typedef
180   struct {
181      UWord _wLO;
182      UWord _wHI;
183      SysResMode _mode;
184   }
185   SysRes;
186#else
187#  error "Unknown OS"
188#endif
189
190
191/* ---- And now some basic accessor functions for it. ---- */
192
193#if defined(VGO_linux)
194
195static inline Bool sr_isError ( SysRes sr ) {
196   return sr._isError;
197}
198static inline UWord sr_Res ( SysRes sr ) {
199   return sr._isError ? 0 : sr._val;
200}
201static inline UWord sr_ResEx ( SysRes sr ) {
202   return sr._isError ? 0 : sr._valEx;
203}
204static inline UWord sr_ResHI ( SysRes sr ) {
205   return 0;
206}
207static inline UWord sr_Err ( SysRes sr ) {
208   return sr._isError ? sr._val : 0;
209}
210static inline Bool sr_EQ ( SysRes sr1, SysRes sr2 ) {
211   return sr1._val == sr2._val
212          && ((sr1._isError && sr2._isError)
213              || (!sr1._isError && !sr2._isError));
214}
215
216#elif defined(VGO_darwin)
217
218static inline Bool sr_isError ( SysRes sr ) {
219   switch (sr._mode) {
220      case SysRes_UNIX_ERR: return True;
221      default:              return False;
222      /* should check tags properly and assert here, but we can't here */
223   }
224}
225
226static inline UWord sr_Res ( SysRes sr ) {
227   switch (sr._mode) {
228      case SysRes_MACH:
229      case SysRes_MDEP:
230      case SysRes_UNIX_OK: return sr._wLO;
231      default: return 0; /* should assert, but we can't here */
232   }
233}
234
235static inline UWord sr_ResHI ( SysRes sr ) {
236   switch (sr._mode) {
237      case SysRes_UNIX_OK: return sr._wHI;
238      default: return 0; /* should assert, but we can't here */
239   }
240}
241
242static inline UWord sr_Err ( SysRes sr ) {
243   switch (sr._mode) {
244      case SysRes_UNIX_ERR: return sr._wLO;
245      default: return 0; /* should assert, but we can't here */
246   }
247}
248
249static inline Bool sr_EQ ( SysRes sr1, SysRes sr2 ) {
250   return sr1._mode == sr2._mode
251          && sr1._wLO == sr2._wLO && sr1._wHI == sr2._wHI;
252}
253
254#else
255#  error "Unknown OS"
256#endif
257
258
259/* ---------------------------------------------------------------------
260   Miscellaneous (word size, endianness, regparmness, stringification)
261   ------------------------------------------------------------------ */
262
263/* Word size: this is going to be either 4 or 8. */
264// It should probably be in m_machine.
265#define VG_WORDSIZE VEX_HOST_WORDSIZE
266
267/* Endianness */
268#undef VG_BIGENDIAN
269#undef VG_LITTLEENDIAN
270
271#if defined(VGA_x86) || defined(VGA_amd64) || defined (VGA_arm) \
272    || ((defined(VGA_mips32) || defined(VGA_mips64)) && defined (_MIPSEL)) \
273    || defined(VGA_arm64)
274#  define VG_LITTLEENDIAN 1
275#elif defined(VGA_ppc32) || defined(VGA_ppc64) || defined(VGA_s390x) \
276      || ((defined(VGA_mips32) || defined(VGA_mips64)) && defined (_MIPSEB))
277#  define VG_BIGENDIAN 1
278#else
279#  error Unknown arch
280#endif
281
282/* Regparmness */
283#if defined(VGA_x86)
284#  define VG_REGPARM(n)            __attribute__((regparm(n)))
285#elif defined(VGA_amd64) || defined(VGA_ppc32) \
286      || defined(VGA_ppc64) || defined(VGA_arm) || defined(VGA_s390x) \
287      || defined(VGA_mips32) || defined(VGA_mips64) \
288      || defined(VGA_arm64)
289#  define VG_REGPARM(n)            /* */
290#else
291#  error Unknown arch
292#endif
293
294/* Macro games */
295#define VG_STRINGIFZ(__str)  #__str
296#define VG_STRINGIFY(__str)  VG_STRINGIFZ(__str)
297
298// Where to send bug reports to.
299#define VG_BUGS_TO "www.valgrind.org"
300
301/* Branch prediction hints. */
302#if defined(__GNUC__)
303#  define LIKELY(x)   __builtin_expect(!!(x), 1)
304#  define UNLIKELY(x) __builtin_expect(!!(x), 0)
305#else
306#  define LIKELY(x)   (x)
307#  define UNLIKELY(x) (x)
308#endif
309
310// printf format string checking for gcc.
311// This feature has been supported since at least gcc version 2.95.
312// For more information about the format attribute, see
313// http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Function-Attributes.html.
314#if defined(__GNUC__)
315#define PRINTF_CHECK(x, y) __attribute__((format(__printf__, x, y)))
316#else
317#define PRINTF_CHECK(x, y)
318#endif
319
320
321#endif /* __PUB_TOOL_BASICS_H */
322
323/*--------------------------------------------------------------------*/
324/*--- end                                                          ---*/
325/*--------------------------------------------------------------------*/
326