libitm/doc/the-libitm-abi/function-list.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 Function list
   7 *************
   8
   9 Initialization and finalization functions
  10 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  11
  12 These functions are not part of the ABI.
  13
  14 [No changes] Version checking
  15 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  16
  17 [No changes] Error reporting
  18 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  19
  20 [No changes] inTransaction call
  21 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  22
  23 State manipulation functions
  24 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  25
  26 There is no ``getTransaction`` function. Transaction identifiers for
  27 nested transactions will be ordered but not necessarily sequential (i.e., for
  28 a nested transaction's identifier :samp:`{IN}` and its enclosing transaction's
  29 identifier :samp:`{IE}`, it is guaranteed that IN >= IE).
  30
  31 [No changes] Source locations
  32 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  33
  34 Starting a transaction
  35 ^^^^^^^^^^^^^^^^^^^^^^
  36
  37 .. _txn-code-properties:
  38
  39 Transaction code properties
  40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  41
  42 The bit ``hasNoXMMUpdate`` is instead called ``hasNoVectorUpdate``.
  43 Iff it is set, vector register save/restore is not necessary for any target
  44 machine.
  45
  46 The ``hasNoFloatUpdate`` bit (``0x0010``) is new. Iff it is set, floating
  47 point register save/restore is not necessary for any target machine.
  48
  49 ``undoLogCode`` is not supported and a fatal runtime error will be raised
  50 if this bit is set. It is not properly defined in the ABI why barriers
  51 other than undo logging are not present; Are they not necessary (e.g., a
  52 transaction operating purely on thread-local data) or have they been omitted by
  53 the compiler because it thinks that some kind of global synchronization
  54 (e.g., serial mode) might perform better? The specification suggests that the
  55 latter might be the case, but the former seems to be more useful.
  56
  57 The ``readOnly`` bit (``0x4000``) is new.
  58
  59 .. todo:: Lexical or dynamic scope?
  60
  61 ``hasNoRetry`` is not supported. If this bit is not set, but
  62 ``hasNoAbort`` is set, the library can assume that transaction
  63 rollback will not be requested.
  64
  65 It would be useful if the absence of externally-triggered rollbacks would be
  66 reported for the dynamic scope as well, not just for the lexical scope
  67 (``hasNoAbort``). Without this, a library cannot exploit this together
  68 with flat nesting.
  69
  70 ``exceptionBlock`` is not supported because exception blocks are not used.
  71
  72 [No changes] Windows exception state
  73 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  74
  75 [No changes] Other machine state
  76 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  77
  78 [No changes] Results from beginTransaction
  79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  80
  81 Aborting a transaction
  82 ^^^^^^^^^^^^^^^^^^^^^^
  83
  84 ``_ITM_rollbackTransaction`` is not supported. ``_ITM_abortTransaction``
  85 is supported but the abort reasons ``exceptionBlockAbort``,
  86 ``TMConflict``, and ``userRetry`` are not supported. There are no
  87 exception blocks in general, so the related cases also do not have to be
  88 considered. To encode ``__transaction_cancel [[outer]]``, compilers must
  89 set the new ``outerAbort`` bit (``0x10``) additionally to the
  90 ``userAbort`` bit in the abort reason.
  91
  92 Committing a transaction
  93 ^^^^^^^^^^^^^^^^^^^^^^^^
  94
  95 The exception handling (EH) scheme is different. The Intel ABI requires the
  96 ``_ITM_tryCommitTransaction`` function that will return even when the
  97 commit failed and will have to be matched with calls to either
  98 ``_ITM_abortTransaction`` or ``_ITM_commitTransaction``. In contrast,
  99 gcc relies on transactional wrappers for the functions of the Exception
 100 Handling ABI and on one additional commit function (shown below). This allows
 101 the TM to keep track of EH internally and thus it does not have to embed the
 102 cleanup of EH state into the existing EH code in the program.
 103 ``_ITM_tryCommitTransaction`` is not supported.
 104 ``_ITM_commitTransactionToId`` is also not supported because the
 105 propagation of thrown exceptions will not bypass commits of nested
 106 transactions.
 107
 108 .. code-block:: c++
 109
 110   void _ITM_commitTransactionEH(void *exc_ptr) ITM_REGPARM;
 111   void *_ITM_cxa_allocate_exception (size_t);
 112   void _ITM_cxa_free_exception (void *exc_ptr);
 113   void _ITM_cxa_throw (void *obj, void *tinfo, void (*dest) (void *));
 114   void *_ITM_cxa_begin_catch (void *exc_ptr);
 115   void _ITM_cxa_end_catch (void);
 116
 117 The EH scheme changed in version 6 of GCC.  Previously, the compiler
 118 added a call to ``_ITM_commitTransactionEH`` to commit a transaction if
 119 an exception could be in flight at this position in the code; ``exc_ptr`` is
 120 the address of the current exception and must be non-zero.  Now, the
 121 compiler must catch all exceptions that are about to be thrown out of a
 122 transaction and call ``_ITM_commitTransactionEH`` from the catch clause,
 123 with ``exc_ptr`` being zero.
 124
 125 Note that the old EH scheme never worked completely in GCC's implementation;
 126 libitm currently does not try to be compatible with the old scheme.
 127
 128 The ``_ITM_cxa...`` functions are transactional wrappers for the respective
 129 ``__cxa...`` functions and must be called instead of these in transactional
 130 code.  ``_ITM_cxa_free_exception`` is new in GCC 6.
 131
 132 To support this EH scheme, libstdc++ needs to provide one additional function
 133 (``_cxa_tm_cleanup``), which is used by the TM to clean up the exception
 134 handling state while rolling back a transaction:
 135
 136 .. code-block:: c++
 137
 138   void __cxa_tm_cleanup (void *unthrown_obj, void *cleanup_exc,
 139                          unsigned int caught_count);
 140
 141 Since GCC 6, ``unthrown_obj`` is not used anymore and always null;
 142 prior to that, ``unthrown_obj`` is non-null if the program called
 143 ``__cxa_allocate_exception`` for this exception but did not yet called
 144 ``__cxa_throw`` for it. ``cleanup_exc`` is non-null if the program is
 145 currently processing a cleanup along an exception path but has not caught this
 146 exception yet. ``caught_count`` is the nesting depth of
 147 ``__cxa_begin_catch`` within the transaction (which can be counted by the TM
 148 using ``_ITM_cxa_begin_catch`` and ``_ITM_cxa_end_catch``);
 149 ``__cxa_tm_cleanup`` then performs rollback by essentially performing
 150 ``__cxa_end_catch`` that many times.
 151
 152 Exception handling support
 153 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 154
 155 Currently, there is no support for functionality like
 156 ``__transaction_cancel throw`` as described in the C++ TM specification.
 157 Supporting this should be possible with the EH scheme explained previously
 158 because via the transactional wrappers for the EH ABI, the TM is able to
 159 observe and intercept EH.
 160
 161 [No changes] Transition to serial--irrevocable mode
 162 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 163
 164 [No changes] Data transfer functions
 165 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 166
 167 [No changes] Transactional memory copies
 168 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 169
 170 Transactional versions of memmove
 171 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 172
 173 If either the source or destination memory region is to be accessed
 174 nontransactionally, then source and destination regions must not be
 175 overlapping. The respective ``_ITM_memmove`` functions are still
 176 available but a fatal runtime error will be raised if such regions do overlap.
 177 To support this functionality, the ABI would have to specify how the
 178 intersection of the regions has to be accessed (i.e., transactionally or
 179 nontransactionally).
 180
 181 [No changes] Transactional versions of memset
 182 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 183
 184 [No changes] Logging functions
 185 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 186
 187 User-registered commit and undo actions
 188 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 189
 190 Commit actions will get executed in the same order in which the respective
 191 calls to ``_ITM_addUserCommitAction`` happened. Only
 192 ``_ITM_noTransactionId`` is allowed as value for the
 193 ``resumingTransactionId`` argument. Commit actions get executed after
 194 privatization safety has been ensured.
 195
 196 Undo actions will get executed in reverse order compared to the order in which
 197 the respective calls to ``_ITM_addUserUndoAction`` happened. The ordering of
 198 undo actions w.r.t. the roll-back of other actions (e.g., data transfers or
 199 memory allocations) is undefined.
 200
 201 ``_ITM_getThreadnum`` is not supported currently because its only purpose
 202 is to provide a thread ID that matches some assumed performance tuning output,
 203 but this output is not part of the ABI nor further defined by it.
 204
 205 ``_ITM_dropReferences`` is not supported currently because its semantics and
 206 the intention behind it is not entirely clear. The
 207 specification suggests that this function is necessary because of certain
 208 orderings of data transfer undos and the releasing of memory regions (i.e.,
 209 privatization). However, this ordering is never defined, nor is the ordering of
 210 dropping references w.r.t. other events.
 211
 212 [New] Transactional indirect calls
 213 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 214
 215 Indirect calls (i.e., calls through a function pointer) within transactions
 216 should execute the transactional clone of the original function (i.e., a clone
 217 of the original that has been fully instrumented to use the TM runtime), if
 218 such a clone is available. The runtime provides two functions to
 219 register/deregister clone tables:
 220
 221 .. code-block:: c++
 222
 223   struct clone_entry
 224   {
 225     void *orig, *clone;
 226   };
 227
 228   void _ITM_registerTMCloneTable (clone_entry *table, size_t entries);
 229   void _ITM_deregisterTMCloneTable (clone_entry *table);
 230
 231 Registered tables must be writable by the TM runtime, and must be live
 232 throughout the life-time of the TM runtime.
 233
 234 .. todo:: The intention was always to drop the registration functions
 235   entirely, and create a new ELF Phdr describing the linker-sorted table.  Much
 236   like what currently happens for ``PT_GNU_EH_FRAME``.
 237   This work kept getting bogged down in how to represent the :samp:`{N}` different
 238   code generation variants.  We clearly needed at least two---SW and HW
 239   transactional clones---but there was always a suggestion of more variants for
 240   different TM assumptions/invariants.
 241
 242 The compiler can then use two TM runtime functions to perform indirect calls in
 243 transactions:
 244
 245 .. code-block:: c++
 246
 247   void *_ITM_getTMCloneOrIrrevocable (void *function) ITM_REGPARM;
 248   void *_ITM_getTMCloneSafe (void *function) ITM_REGPARM;
 249
 250 If there is a registered clone for supplied function, both will return a
 251 pointer to the clone. If not, the first runtime function will attempt to switch
 252 to serial--irrevocable mode and return the original pointer, whereas the second
 253 will raise a fatal runtime error.
 254
 255 [New] Transactional dynamic memory management
 256 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 257
 258 .. code-block:: c++
 259
 260   void *_ITM_malloc (size_t)
 261          __attribute__((__malloc__)) ITM_PURE;
 262   void *_ITM_calloc (size_t, size_t)
 263          __attribute__((__malloc__)) ITM_PURE;
 264   void _ITM_free (void *) ITM_PURE;
 265
 266 These functions are essentially transactional wrappers for ``malloc``,
 267 ``calloc``, and ``free``. Within transactions, the compiler should
 268 replace calls to the original functions with calls to the wrapper functions.
 269
 270 libitm also provides transactional clones of C++ memory management functions
 271 such as global operator new and delete.  They are part of libitm for historic
 272 reasons but do not need to be part of this ABI.