libitm/libitm.h

   1 /* Copyright (C) 2008-2023 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 #ifdef _GLIBCXX_NOTHROW
  49 # define _ITM_NOTHROW _GLIBCXX_NOTHROW
  50 #elif !defined (__cplusplus)
  51 # define _ITM_NOTHROW __attribute__((__nothrow__))
  52 #elif __cplusplus < 201103L
  53 # define _ITM_NOTHROW throw ()
  54 #else
  55 # define _ITM_NOTHROW noexcept
  56 #endif
  57
  58 /* The following are externally visible definitions and functions, though
  59    only very few of these should be called by user code.  */
  60
  61 /* Values used as arguments to abort. */
  62 typedef enum {
  63     userAbort = 1,
  64     userRetry = 2,
  65     TMConflict= 4,
  66     exceptionBlockAbort = 8,
  67     outerAbort = 16
  68 } _ITM_abortReason;
  69
  70 /* Arguments to changeTransactionMode */
  71 typedef enum
  72 {
  73     modeSerialIrrevocable,
  74 } _ITM_transactionState;
  75
  76 /* Results from inTransaction */
  77 typedef enum
  78 {
  79     outsideTransaction = 0,    /* So "if (inTransaction(td))" works */
  80     inRetryableTransaction,
  81     inIrrevocableTransaction
  82 } _ITM_howExecuting;
  83
  84 /* Values to describe properties of code, passed in to beginTransaction.
  85    Some of these constants are duplicated in some of the ITM_beginTransaction
  86    implementations, so update those too when applying any changes.  */
  87 typedef enum
  88 {
  89    pr_instrumentedCode          = 0x0001,
  90    pr_uninstrumentedCode        = 0x0002,
  91    pr_multiwayCode              = pr_instrumentedCode | pr_uninstrumentedCode,
  92    /* Called pr_hasNoXMMUpdate in the Intel document, used for
  93       avoiding vector register save/restore for any target.  */
  94    pr_hasNoVectorUpdate         = 0x0004,
  95    pr_hasNoAbort                = 0x0008,
  96    /* Not present in the Intel document, used for avoiding
  97       floating point register save/restore for any target.  */
  98    pr_hasNoFloatUpdate          = 0x0010,
  99    pr_hasNoIrrevocable          = 0x0020,
 100    pr_doesGoIrrevocable         = 0x0040,
 101    pr_aWBarriersOmitted         = 0x0100,
 102    pr_RaRBarriersOmitted        = 0x0200,
 103    pr_undoLogCode               = 0x0400,
 104    pr_preferUninstrumented      = 0x0800,
 105    /* Exception blocks are not used nor supported. */
 106    pr_exceptionBlock            = 0x1000,
 107    pr_hasElse                   = 0x2000,
 108    pr_readOnly                  = 0x4000,
 109    pr_hasNoSimpleReads          = 0x400000,
 110    /* These are not part of the ABI but used for custom HTM fast paths.  See
 111       ITM_beginTransaction and gtm_thread::begin_transaction.  */
 112    pr_HTMRetryableAbort         = 0x800000,
 113    pr_HTMRetriedAfterAbort      = 0x1000000
 114 } _ITM_codeProperties;
 115
 116 /* Result from startTransaction that describes what actions to take.
 117    Some of these constants are duplicated in some of the ITM_beginTransaction
 118    implementations, so update those too when applying any changes.  */
 119 typedef enum
 120 {
 121    a_runInstrumentedCode       = 0x01,
 122    a_runUninstrumentedCode     = 0x02,
 123    a_saveLiveVariables         = 0x04,
 124    a_restoreLiveVariables      = 0x08,
 125    a_abortTransaction          = 0x10,
 126    a_tryHTMFastPath            = 0x20
 127 } _ITM_actions;
 128
 129 typedef struct
 130 {
 131     uint32_t reserved_1;
 132     uint32_t flags;
 133     uint32_t reserved_2;
 134     uint32_t reserved_3;
 135     const char *psource;
 136 } _ITM_srcLocation;
 137
 138 typedef void (* _ITM_userUndoFunction)(void *);
 139 typedef void (* _ITM_userCommitFunction) (void *);
 140
 141 #define _ITM_VERSION "0.90 (Feb 29 2008)"
 142 #define _ITM_VERSION_NO 90
 143
 144 extern int _ITM_versionCompatible (int) ITM_REGPARM;
 145 extern const char * _ITM_libraryVersion (void) ITM_REGPARM;
 146
 147 void _ITM_error(const _ITM_srcLocation *, int errorCode)
 148   ITM_REGPARM ITM_NORETURN;
 149
 150 extern _ITM_howExecuting _ITM_inTransaction(void) ITM_REGPARM;
 151
 152 typedef uint64_t _ITM_transactionId_t;  /* Transaction identifier */
 153 #define _ITM_noTransactionId 1          /* Id for non-transactional code. */
 154
 155 extern _ITM_transactionId_t _ITM_getTransactionId(void) ITM_REGPARM;
 156
 157 extern uint32_t _ITM_beginTransaction(uint32_t, ...) ITM_REGPARM;
 158
 159 extern void _ITM_abortTransaction(_ITM_abortReason) ITM_REGPARM ITM_NORETURN;
 160
 161 extern void _ITM_commitTransaction (void) ITM_REGPARM;
 162
 163 extern void _ITM_changeTransactionMode (_ITM_transactionState) ITM_REGPARM;
 164
 165 extern void _ITM_addUserCommitAction(_ITM_userCommitFunction,
 166                                      _ITM_transactionId_t, void *) ITM_REGPARM;
 167
 168 extern void _ITM_addUserUndoAction(_ITM_userUndoFunction, void *) ITM_REGPARM;
 169
 170 extern void _ITM_dropReferences (void *, size_t) ITM_REGPARM ITM_PURE;
 171
 172 extern void *_ITM_malloc (size_t)
 173        __attribute__((__malloc__)) ITM_PURE;
 174
 175 extern void *_ITM_calloc (size_t, size_t)
 176        __attribute__((__malloc__)) ITM_PURE;
 177
 178 extern  void _ITM_free (void *) ITM_PURE;
 179
 180
 181 /* The following typedefs exist to make the macro expansions below work
 182    properly.  They are not part of any API.  */
 183 typedef uint8_t  _ITM_TYPE_U1;
 184 typedef uint16_t _ITM_TYPE_U2;
 185 typedef uint32_t _ITM_TYPE_U4;
 186 typedef uint64_t _ITM_TYPE_U8;
 187 typedef float    _ITM_TYPE_F;
 188 typedef double   _ITM_TYPE_D;
 189 typedef long double _ITM_TYPE_E;
 190 typedef float _Complex _ITM_TYPE_CF;
 191 typedef double _Complex _ITM_TYPE_CD;
 192 typedef long double _Complex _ITM_TYPE_CE;
 193
 194 #define ITM_BARRIERS(T) \
 195   extern _ITM_TYPE_##T _ITM_R##T(const _ITM_TYPE_##T *) ITM_REGPARM;    \
 196   extern _ITM_TYPE_##T _ITM_RaR##T(const _ITM_TYPE_##T *) ITM_REGPARM;  \
 197   extern _ITM_TYPE_##T _ITM_RaW##T(const _ITM_TYPE_##T *) ITM_REGPARM;  \
 198   extern _ITM_TYPE_##T _ITM_RfW##T(const _ITM_TYPE_##T *) ITM_REGPARM;  \
 199   extern void _ITM_W##T (_ITM_TYPE_##T *, _ITM_TYPE_##T) ITM_REGPARM;   \
 200   extern void _ITM_WaR##T (_ITM_TYPE_##T *, _ITM_TYPE_##T) ITM_REGPARM; \
 201   extern void _ITM_WaW##T (_ITM_TYPE_##T *, _ITM_TYPE_##T) ITM_REGPARM;
 202
 203 ITM_BARRIERS(U1)
 204 ITM_BARRIERS(U2)
 205 ITM_BARRIERS(U4)
 206 ITM_BARRIERS(U8)
 207 ITM_BARRIERS(F)
 208 ITM_BARRIERS(D)
 209 ITM_BARRIERS(E)
 210 ITM_BARRIERS(CF)
 211 ITM_BARRIERS(CD)
 212 ITM_BARRIERS(CE)
 213
 214 #define ITM_LOG(T) \
 215   extern void _ITM_L##T (const _ITM_TYPE_##T *) ITM_REGPARM;
 216
 217 ITM_LOG(U1)
 218 ITM_LOG(U2)
 219 ITM_LOG(U4)
 220 ITM_LOG(U8)
 221 ITM_LOG(F)
 222 ITM_LOG(D)
 223 ITM_LOG(E)
 224 ITM_LOG(CF)
 225 ITM_LOG(CD)
 226 ITM_LOG(CE)
 227
 228 #if defined(__i386__) || defined(__x86_64__)
 229 # ifdef __MMX__
 230   typedef int _ITM_TYPE_M64 __attribute__((vector_size(8), may_alias));
 231   ITM_BARRIERS(M64)
 232   ITM_LOG(M64)
 233 # endif
 234 # ifdef __SSE__
 235   typedef float _ITM_TYPE_M128 __attribute__((vector_size(16), may_alias));
 236   ITM_BARRIERS(M128)
 237   ITM_LOG(M128)
 238 # endif
 239 # ifdef __AVX__
 240   typedef float _ITM_TYPE_M256 __attribute__((vector_size(32), may_alias));
 241   ITM_BARRIERS(M256)
 242   ITM_LOG(M256)
 243 # endif
 244 #endif /* i386 */
 245
 246 #undef ITM_BARRIERS
 247 #undef ITM_LOG
 248
 249 extern void _ITM_LB (const void *, size_t) ITM_REGPARM;
 250
 251 extern void _ITM_memcpyRnWt(void *, const void *, size_t) ITM_REGPARM;
 252 extern void _ITM_memcpyRnWtaR(void *, const void *, size_t) ITM_REGPARM;
 253 extern void _ITM_memcpyRnWtaW(void *, const void *, size_t) ITM_REGPARM;
 254 extern void _ITM_memcpyRtWn(void *, const void *, size_t) ITM_REGPARM;
 255 extern void _ITM_memcpyRtWt(void *, const void *, size_t) ITM_REGPARM;
 256 extern void _ITM_memcpyRtWtaR(void *, const void *, size_t) ITM_REGPARM;
 257 extern void _ITM_memcpyRtWtaW(void *, const void *, size_t) ITM_REGPARM;
 258 extern void _ITM_memcpyRtaRWn(void *, const void *, size_t) ITM_REGPARM;
 259 extern void _ITM_memcpyRtaRWt(void *, const void *, size_t) ITM_REGPARM;
 260 extern void _ITM_memcpyRtaRWtaR(void *, const void *, size_t) ITM_REGPARM;
 261 extern void _ITM_memcpyRtaRWtaW(void *, const void *, size_t) ITM_REGPARM;
 262 extern void _ITM_memcpyRtaWWn(void *, const void *, size_t) ITM_REGPARM;
 263 extern void _ITM_memcpyRtaWWt(void *, const void *, size_t) ITM_REGPARM;
 264 extern void _ITM_memcpyRtaWWtaR(void *, const void *, size_t) ITM_REGPARM;
 265 extern void _ITM_memcpyRtaWWtaW(void *, const void *, size_t) ITM_REGPARM;
 266
 267 extern void _ITM_memmoveRnWt(void *, const void *, size_t) ITM_REGPARM;
 268 extern void _ITM_memmoveRnWtaR(void *, const void *, size_t) ITM_REGPARM;
 269 extern void _ITM_memmoveRnWtaW(void *, const void *, size_t) ITM_REGPARM;
 270 extern void _ITM_memmoveRtWn(void *, const void *, size_t) ITM_REGPARM;
 271 extern void _ITM_memmoveRtWt(void *, const void *, size_t) ITM_REGPARM;
 272 extern void _ITM_memmoveRtWtaR(void *, const void *, size_t) ITM_REGPARM;
 273 extern void _ITM_memmoveRtWtaW(void *, const void *, size_t) ITM_REGPARM;
 274 extern void _ITM_memmoveRtaRWn(void *, const void *, size_t) ITM_REGPARM;
 275 extern void _ITM_memmoveRtaRWt(void *, const void *, size_t) ITM_REGPARM;
 276 extern void _ITM_memmoveRtaRWtaR(void *, const void *, size_t) ITM_REGPARM;
 277 extern void _ITM_memmoveRtaRWtaW(void *, const void *, size_t) ITM_REGPARM;
 278 extern void _ITM_memmoveRtaWWn(void *, const void *, size_t) ITM_REGPARM;
 279 extern void _ITM_memmoveRtaWWt(void *, const void *, size_t) ITM_REGPARM;
 280 extern void _ITM_memmoveRtaWWtaR(void *, const void *, size_t) ITM_REGPARM;
 281 extern void _ITM_memmoveRtaWWtaW(void *, const void *, size_t) ITM_REGPARM;
 282
 283 extern void _ITM_memsetW(void *, int, size_t) ITM_REGPARM;
 284 extern void _ITM_memsetWaR(void *, int, size_t) ITM_REGPARM;
 285 extern void _ITM_memsetWaW(void *, int, size_t) ITM_REGPARM;
 286
 287 // ??? These are not yet in the official spec; still work-in-progress.
 288
 289 extern void *_ITM_getTMCloneOrIrrevocable (void *) ITM_REGPARM;
 290 extern void *_ITM_getTMCloneSafe (void *) ITM_REGPARM;
 291 extern void _ITM_registerTMCloneTable (void *, size_t);
 292 extern void _ITM_deregisterTMCloneTable (void *);
 293
 294 extern void *_ITM_cxa_allocate_exception (size_t) _ITM_NOTHROW;
 295 extern void _ITM_cxa_free_exception (void *exc_ptr) _ITM_NOTHROW;
 296 extern void _ITM_cxa_throw (void *obj, void *tinfo, void (*dest) (void *));
 297 extern void *_ITM_cxa_begin_catch (void *exc_ptr) _ITM_NOTHROW;
 298 extern void _ITM_cxa_end_catch (void); /* This can throw.  */
 299 extern void _ITM_commitTransactionEH(void *exc_ptr) ITM_REGPARM;
 300
 301 #ifdef __cplusplus
 302 } /* extern "C" */
 303 #endif
 304
 305 #endif /* LIBITM_H */