libitm/libitm.h

   1 /* Copyright (C) 2008-2013 Free Software Foundation, Inc.
   2    Contributed by Richard Henderson <rth@redhat.com>.
   3
   4    This file is part of the GNU Transactional Memory Library (libitm).
   5
   6    Libitm is free software; you can redistribute it and/or modify it
   7    under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    Libitm is distributed in the hope that it will be useful, but WITHOUT ANY
  12    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  13    FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  14    more details.
  15
  16    Under Section 7 of GPL version 3, you are granted additional
  17    permissions described in the GCC Runtime Library Exception, version
  18    3.1, as published by the Free Software Foundation.
  19
  20    You should have received a copy of the GNU General Public License and
  21    a copy of the GCC Runtime Library Exception along with this program;
  22    see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  23    <http://www.gnu.org/licenses/>.  */
  24
  25 /* The external interface of this library follows the specification described
  26    in version 1 of http://www.intel.com/some/path/here.pdf.  */
  27
  28 #ifndef LIBITM_H
  29 #define LIBITM_H 1
  30
  31 #include <stddef.h>
  32 #include <stdbool.h>
  33 #include <stdint.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 #ifdef __i386__
  40 /* Only for 32-bit x86.  */
  41 # define ITM_REGPARM    __attribute__((regparm(2)))
  42 #else
  43 # define ITM_REGPARM
  44 #endif
  45
  46 #define ITM_NORETURN    __attribute__((noreturn))
  47 #define ITM_PURE __attribute__((transaction_pure))
  48
  49 /* The following are externally visible definitions and functions, though
  50    only very few of these should be called by user code.  */
  51
  52 /* Values used as arguments to abort. */
  53 typedef enum {
  54     userAbort = 1,
  55     userRetry = 2,
  56     TMConflict= 4,
  57     exceptionBlockAbort = 8,
  58     outerAbort = 16
  59 } _ITM_abortReason;
  60
  61 /* Arguments to changeTransactionMode */
  62 typedef enum
  63 {
  64     modeSerialIrrevocable,
  65 } _ITM_transactionState;
  66
  67 /* Results from inTransaction */
  68 typedef enum
  69 {
  70     outsideTransaction = 0,    /* So "if (inTransaction(td))" works */
  71     inRetryableTransaction,
  72     inIrrevocableTransaction
  73 } _ITM_howExecuting;
  74
  75 /* Values to describe properties of code, passed in to beginTransaction */
  76 typedef enum
  77 {
  78    pr_instrumentedCode          = 0x0001,
  79    pr_uninstrumentedCode        = 0x0002,
  80    pr_multiwayCode              = pr_instrumentedCode | pr_uninstrumentedCode,
  81    /* Called pr_hasNoXMMUpdate in the Intel document, used for
  82       avoiding vector register save/restore for any target.  */
  83    pr_hasNoVectorUpdate         = 0x0004,
  84    pr_hasNoAbort                = 0x0008,
  85    /* Not present in the Intel document, used for avoiding
  86       floating point register save/restore for any target.  */
  87    pr_hasNoFloatUpdate          = 0x0010,
  88    pr_hasNoIrrevocable          = 0x0020,
  89    pr_doesGoIrrevocable         = 0x0040,
  90    pr_aWBarriersOmitted         = 0x0100,
  91    pr_RaRBarriersOmitted        = 0x0200,
  92    pr_undoLogCode               = 0x0400,
  93    pr_preferUninstrumented      = 0x0800,
  94    /* Exception blocks are not used nor supported. */
  95    pr_exceptionBlock            = 0x1000,
  96    pr_hasElse                   = 0x2000,
  97    pr_readOnly                  = 0x4000,
  98    pr_hasNoSimpleReads          = 0x400000
  99 } _ITM_codeProperties;
 100
 101 /* Result from startTransaction that describes what actions to take.  */
 102 typedef enum
 103 {
 104    a_runInstrumentedCode       = 0x01,
 105    a_runUninstrumentedCode     = 0x02,
 106    a_saveLiveVariables         = 0x04,
 107    a_restoreLiveVariables      = 0x08,
 108    a_abortTransaction          = 0x10,
 109 } _ITM_actions;
 110
 111 typedef struct
 112 {
 113     uint32_t reserved_1;
 114     uint32_t flags;
 115     uint32_t reserved_2;
 116     uint32_t reserved_3;
 117     const char *psource;
 118 } _ITM_srcLocation;
 119
 120 typedef void (* _ITM_userUndoFunction)(void *);
 121 typedef void (* _ITM_userCommitFunction) (void *);
 122
 123 #define _ITM_VERSION "0.90 (Feb 29 2008)"
 124 #define _ITM_VERSION_NO 90
 125
 126 extern int _ITM_versionCompatible (int) ITM_REGPARM;
 127 extern const char * _ITM_libraryVersion (void) ITM_REGPARM;
 128
 129 void _ITM_error(const _ITM_srcLocation *, int errorCode)
 130   ITM_REGPARM ITM_NORETURN;
 131
 132 extern _ITM_howExecuting _ITM_inTransaction(void) ITM_REGPARM;
 133
 134 typedef uint64_t _ITM_transactionId_t;  /* Transaction identifier */
 135 #define _ITM_noTransactionId 1          /* Id for non-transactional code. */
 136
 137 extern _ITM_transactionId_t _ITM_getTransactionId(void) ITM_REGPARM;
 138
 139 extern uint32_t _ITM_beginTransaction(uint32_t, ...) ITM_REGPARM;
 140
 141 extern void _ITM_abortTransaction(_ITM_abortReason) ITM_REGPARM ITM_NORETURN;
 142
 143 extern void _ITM_commitTransaction (void) ITM_REGPARM;
 144
 145 extern void _ITM_changeTransactionMode (_ITM_transactionState) ITM_REGPARM;
 146
 147 extern void _ITM_addUserCommitAction(_ITM_userCommitFunction,
 148                                      _ITM_transactionId_t, void *) ITM_REGPARM;
 149
 150 extern void _ITM_addUserUndoAction(_ITM_userUndoFunction, void *) ITM_REGPARM;
 151
 152 extern void _ITM_dropReferences (void *, size_t) ITM_REGPARM ITM_PURE;
 153
 154 extern void *_ITM_malloc (size_t)
 155        __attribute__((__malloc__)) ITM_PURE;
 156
 157 extern void *_ITM_calloc (size_t, size_t)
 158        __attribute__((__malloc__)) ITM_PURE;
 159
 160 extern  void _ITM_free (void *) ITM_PURE;
 161
 162
 163 /* The following typedefs exist to make the macro expansions below work
 164    properly.  They are not part of any API.  */
 165 typedef uint8_t  _ITM_TYPE_U1;
 166 typedef uint16_t _ITM_TYPE_U2;
 167 typedef uint32_t _ITM_TYPE_U4;
 168 typedef uint64_t _ITM_TYPE_U8;
 169 typedef float    _ITM_TYPE_F;
 170 typedef double   _ITM_TYPE_D;
 171 typedef long double _ITM_TYPE_E;
 172 typedef float _Complex _ITM_TYPE_CF;
 173 typedef double _Complex _ITM_TYPE_CD;
 174 typedef long double _Complex _ITM_TYPE_CE;
 175
 176 #define ITM_BARRIERS(T) \
 177   extern _ITM_TYPE_##T _ITM_R##T(const _ITM_TYPE_##T *) ITM_REGPARM;    \
 178   extern _ITM_TYPE_##T _ITM_RaR##T(const _ITM_TYPE_##T *) ITM_REGPARM;  \
 179   extern _ITM_TYPE_##T _ITM_RaW##T(const _ITM_TYPE_##T *) ITM_REGPARM;  \
 180   extern _ITM_TYPE_##T _ITM_RfW##T(const _ITM_TYPE_##T *) ITM_REGPARM;  \
 181   extern void _ITM_W##T (_ITM_TYPE_##T *, _ITM_TYPE_##T) ITM_REGPARM;   \
 182   extern void _ITM_WaR##T (_ITM_TYPE_##T *, _ITM_TYPE_##T) ITM_REGPARM; \
 183   extern void _ITM_WaW##T (_ITM_TYPE_##T *, _ITM_TYPE_##T) ITM_REGPARM;
 184
 185 ITM_BARRIERS(U1)
 186 ITM_BARRIERS(U2)
 187 ITM_BARRIERS(U4)
 188 ITM_BARRIERS(U8)
 189 ITM_BARRIERS(F)
 190 ITM_BARRIERS(D)
 191 ITM_BARRIERS(E)
 192 ITM_BARRIERS(CF)
 193 ITM_BARRIERS(CD)
 194 ITM_BARRIERS(CE)
 195
 196 #define ITM_LOG(T) \
 197   extern void _ITM_L##T (const _ITM_TYPE_##T *) ITM_REGPARM;
 198
 199 ITM_LOG(U1)
 200 ITM_LOG(U2)
 201 ITM_LOG(U4)
 202 ITM_LOG(U8)
 203 ITM_LOG(F)
 204 ITM_LOG(D)
 205 ITM_LOG(E)
 206 ITM_LOG(CF)
 207 ITM_LOG(CD)
 208 ITM_LOG(CE)
 209
 210 #if defined(__i386__) || defined(__x86_64__)
 211 # ifdef __MMX__
 212   typedef int _ITM_TYPE_M64 __attribute__((vector_size(8), may_alias));
 213   ITM_BARRIERS(M64)
 214   ITM_LOG(M64)
 215 # endif
 216 # ifdef __SSE__
 217   typedef float _ITM_TYPE_M128 __attribute__((vector_size(16), may_alias));
 218   ITM_BARRIERS(M128)
 219   ITM_LOG(M128)
 220 # endif
 221 # ifdef __AVX__
 222   typedef float _ITM_TYPE_M256 __attribute__((vector_size(32), may_alias));
 223   ITM_BARRIERS(M256)
 224   ITM_LOG(M256)
 225 # endif
 226 #endif /* i386 */
 227
 228 #undef ITM_BARRIERS
 229 #undef ITM_LOG
 230
 231 extern void _ITM_LB (const void *, size_t) ITM_REGPARM;
 232
 233 extern void _ITM_memcpyRnWt(void *, const void *, size_t) ITM_REGPARM;
 234 extern void _ITM_memcpyRnWtaR(void *, const void *, size_t) ITM_REGPARM;
 235 extern void _ITM_memcpyRnWtaW(void *, const void *, size_t) ITM_REGPARM;
 236 extern void _ITM_memcpyRtWn(void *, const void *, size_t) ITM_REGPARM;
 237 extern void _ITM_memcpyRtWt(void *, const void *, size_t) ITM_REGPARM;
 238 extern void _ITM_memcpyRtWtaR(void *, const void *, size_t) ITM_REGPARM;
 239 extern void _ITM_memcpyRtWtaW(void *, const void *, size_t) ITM_REGPARM;
 240 extern void _ITM_memcpyRtaRWn(void *, const void *, size_t) ITM_REGPARM;
 241 extern void _ITM_memcpyRtaRWt(void *, const void *, size_t) ITM_REGPARM;
 242 extern void _ITM_memcpyRtaRWtaR(void *, const void *, size_t) ITM_REGPARM;
 243 extern void _ITM_memcpyRtaRWtaW(void *, const void *, size_t) ITM_REGPARM;
 244 extern void _ITM_memcpyRtaWWn(void *, const void *, size_t) ITM_REGPARM;
 245 extern void _ITM_memcpyRtaWWt(void *, const void *, size_t) ITM_REGPARM;
 246 extern void _ITM_memcpyRtaWWtaR(void *, const void *, size_t) ITM_REGPARM;
 247 extern void _ITM_memcpyRtaWWtaW(void *, const void *, size_t) ITM_REGPARM;
 248
 249 extern void _ITM_memmoveRnWt(void *, const void *, size_t) ITM_REGPARM;
 250 extern void _ITM_memmoveRnWtaR(void *, const void *, size_t) ITM_REGPARM;
 251 extern void _ITM_memmoveRnWtaW(void *, const void *, size_t) ITM_REGPARM;
 252 extern void _ITM_memmoveRtWn(void *, const void *, size_t) ITM_REGPARM;
 253 extern void _ITM_memmoveRtWt(void *, const void *, size_t) ITM_REGPARM;
 254 extern void _ITM_memmoveRtWtaR(void *, const void *, size_t) ITM_REGPARM;
 255 extern void _ITM_memmoveRtWtaW(void *, const void *, size_t) ITM_REGPARM;
 256 extern void _ITM_memmoveRtaRWn(void *, const void *, size_t) ITM_REGPARM;
 257 extern void _ITM_memmoveRtaRWt(void *, const void *, size_t) ITM_REGPARM;
 258 extern void _ITM_memmoveRtaRWtaR(void *, const void *, size_t) ITM_REGPARM;
 259 extern void _ITM_memmoveRtaRWtaW(void *, const void *, size_t) ITM_REGPARM;
 260 extern void _ITM_memmoveRtaWWn(void *, const void *, size_t) ITM_REGPARM;
 261 extern void _ITM_memmoveRtaWWt(void *, const void *, size_t) ITM_REGPARM;
 262 extern void _ITM_memmoveRtaWWtaR(void *, const void *, size_t) ITM_REGPARM;
 263 extern void _ITM_memmoveRtaWWtaW(void *, const void *, size_t) ITM_REGPARM;
 264
 265 extern void _ITM_memsetW(void *, int, size_t) ITM_REGPARM;
 266 extern void _ITM_memsetWaR(void *, int, size_t) ITM_REGPARM;
 267 extern void _ITM_memsetWaW(void *, int, size_t) ITM_REGPARM;
 268
 269 // ??? These are not yet in the official spec; still work-in-progress.
 270
 271 extern void *_ITM_getTMCloneOrIrrevocable (void *) ITM_REGPARM;
 272 extern void *_ITM_getTMCloneSafe (void *) ITM_REGPARM;
 273 extern void _ITM_registerTMCloneTable (void *, size_t);
 274 extern void _ITM_deregisterTMCloneTable (void *);
 275
 276 extern void *_ITM_cxa_allocate_exception (size_t);
 277 extern void _ITM_cxa_throw (void *obj, void *tinfo, void *dest);
 278 extern void *_ITM_cxa_begin_catch (void *exc_ptr);
 279 extern void _ITM_cxa_end_catch (void);
 280 extern void _ITM_commitTransactionEH(void *exc_ptr) ITM_REGPARM;
 281
 282 #ifdef __cplusplus
 283 } /* extern "C" */
 284 #endif
 285
 286 #endif /* LIBITM_H */