diff options
Diffstat (limited to 'libitm')
20 files changed, 0 insertions, 894 deletions
diff --git a/libitm/doc/c-c++-language-constructs-for-tm.rst b/libitm/doc/c-c++-language-constructs-for-tm.rst deleted file mode 100644 index 8487eae034b..00000000000 --- a/libitm/doc/c-c++-language-constructs-for-tm.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. _c-c++-language-constructs-for-tm: - -C/C++ Language Constructs for TM --------------------------------- - -Transactions are supported in C++ and C in the form of transaction statements, -transaction expressions, and function transactions. In the following example, -both ``a`` and ``b`` will be read and the difference will be written to -``c``, all atomically and isolated from other transactions: - -.. code-block:: c++ - - __transaction_atomic { c = a - b; } - -Therefore, another thread can use the following code to concurrently update -``b`` without ever causing ``c`` to hold a negative value (and without -having to use other synchronization constructs such as locks or C++11 -atomics): - -.. code-block:: c++ - - __transaction_atomic { if (a > b) b++; } - -GCC follows the `Draft -Specification of Transactional Language Constructs for C++ (v1.1) <https://sites.google.com/site/tmforcplusplus/>`_ in its -implementation of transactions. - -The precise semantics of transactions are defined in terms of the C++11/C11 -memory model (see the specification). Roughly, transactions provide -synchronization guarantees that are similar to what would be guaranteed when -using a single global lock as a guard for all transactions. Note that like -other synchronization constructs in C/C++, transactions rely on a -data-race-free program (e.g., a nontransactional write that is concurrent -with a transactional read to the same memory location is a data race).
\ No newline at end of file diff --git a/libitm/doc/conf.py b/libitm/doc/conf.py deleted file mode 100644 index c288e34fdba..00000000000 --- a/libitm/doc/conf.py +++ /dev/null @@ -1,24 +0,0 @@ -# Configuration file for the Sphinx documentation builder. - -import sys -sys.path.append('../..//doc') - -from baseconf import * - -name = 'libitm' -project = 'The GNU Transactional Memory Library' -copyright = '2011-2022 Free Software Foundation, Inc.' -authors = 'GCC Developer Community' - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -latex_documents = [ - ('index', f'{name}.tex', project, authors, 'manual'), -] - -texinfo_documents = [ - ('index', name, project, authors, None, None, None, True) -] - -set_common(name, globals())
\ No newline at end of file diff --git a/libitm/doc/copyright.rst b/libitm/doc/copyright.rst deleted file mode 100644 index f0a7a075ef7..00000000000 --- a/libitm/doc/copyright.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the GPL license file - -Copyright -^^^^^^^^^ - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled :ref:`gnu_fdl`.
\ No newline at end of file diff --git a/libitm/doc/enabling-libitm.rst b/libitm/doc/enabling-libitm.rst deleted file mode 100644 index 212c120c387..00000000000 --- a/libitm/doc/enabling-libitm.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. _enabling-libitm: - -Enabling libitm ---------------- - -To activate support for TM in C/C++, the compile-time flag :option:`-fgnu-tm` -must be specified. This enables TM language-level constructs such as -transaction statements (e.g., ``__transaction_atomic``, see :ref:`c-c++-language-constructs-for-tm` for details).
\ No newline at end of file diff --git a/libitm/doc/gnu-free-documentation-license.rst b/libitm/doc/gnu-free-documentation-license.rst deleted file mode 100644 index 089cc682de2..00000000000 --- a/libitm/doc/gnu-free-documentation-license.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. include:: ../../doc/gnu_free_documentation_license.rst
\ No newline at end of file diff --git a/libitm/doc/index.rst b/libitm/doc/index.rst deleted file mode 100644 index 45ff20f332b..00000000000 --- a/libitm/doc/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -GCC libquadmath -=============== - -Introduction -============ - -.. index:: Introduction - -This manual documents the usage and internals of libitm, the GNU Transactional -Memory Library. It provides transaction support for accesses to a process' -memory, enabling easy-to-use synchronization of accesses to shared memory by -several threads. - -.. toctree:: - - copyright - enabling-libitm - c-c++-language-constructs-for-tm - the-libitm-abi - internals - gnu-free-documentation-license - indices-and-tables
\ No newline at end of file diff --git a/libitm/doc/indices-and-tables.rst b/libitm/doc/indices-and-tables.rst deleted file mode 100644 index 9799e4e2e48..00000000000 --- a/libitm/doc/indices-and-tables.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../doc/indices-and-tables.rst
\ No newline at end of file diff --git a/libitm/doc/internals.rst b/libitm/doc/internals.rst deleted file mode 100644 index 2e1c24c4e80..00000000000 --- a/libitm/doc/internals.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. _internals: - -Internals ---------- - -.. toctree:: - :maxdepth: 2 - - tm-methods-and-method-groups - nesting-flat-vs-closed - locking-conventions
\ No newline at end of file diff --git a/libitm/doc/locking-conventions.rst b/libitm/doc/locking-conventions.rst deleted file mode 100644 index b7a8d310f08..00000000000 --- a/libitm/doc/locking-conventions.rst +++ /dev/null @@ -1,261 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -Locking conventions -******************* - -This section documents the locking scheme and rules for all uses of locking -in libitm. We have to support serial(-irrevocable) mode, which is implemented -using a global lock as explained next (called the *serial lock*). To -simplify the overall design, we use the same lock as catch-all locking -mechanism for other infrequent tasks such as (de)registering clone tables or -threads. Besides the serial lock, there are *per-method-group locks* that -are managed by specific method groups (i.e., groups of similar TM concurrency -control algorithms), and lock-like constructs for quiescence-based operations -such as ensuring privatization safety. - -Thus, the actions that participate in the libitm-internal locking are either -*active transactions* that do not run in serial mode, *serial -transactions* (which (are about to) run in serial mode), and management tasks -that do not execute within a transaction but have acquired the serial mode -like a serial transaction would do (e.g., to be able to register threads with -libitm). Transactions become active as soon as they have successfully used the -serial lock to announce this globally (see :ref:`serial-lock-impl`). Likewise, transactions become serial transactions as soon as -they have acquired the exclusive rights provided by the serial lock (i.e., -serial mode, which also means that there are no other concurrent active or -serial transactions). Note that active transactions can become serial -transactions when they enter serial mode during the runtime of the -transaction. - -State-to-lock mapping -^^^^^^^^^^^^^^^^^^^^^ - -Application data is protected by the serial lock if there is a serial -transaction and no concurrently running active transaction (i.e., non-serial). -Otherwise, application data is protected by the currently selected method -group, which might use per-method-group locks or other mechanisms. Also note -that application data that is about to be privatized might not be allowed to be -accessed by nontransactional code until privatization safety has been ensured; -the details of this are handled by the current method group. - -libitm-internal state is either protected by the serial lock or accessed -through custom concurrent code. The latter applies to the public/shared part -of a transaction object and most typical method-group-specific state. - -The former category (protected by the serial lock) includes: - -* The list of active threads that have used transactions. - -* The tables that map functions to their transactional clones. - -* The current selection of which method group to use. - -* Some method-group-specific data, or invariants of this data. For example, - resetting a method group to its initial state is handled by switching to the - same method group, so the serial lock protects such resetting as well. - -In general, such state is immutable whenever there exists an active -(non-serial) transaction. If there is no active transaction, a serial -transaction (or a thread that is not currently executing a transaction but has -acquired the serial lock) is allowed to modify this state (but must of course -be careful to not surprise the current method group's implementation with such -modifications). - -Lock acquisition order -^^^^^^^^^^^^^^^^^^^^^^ - -To prevent deadlocks, locks acquisition must happen in a globally agreed-upon -order. Note that this applies to other forms of blocking too, but does not -necessarily apply to lock acquisitions that do not block (e.g., trylock() -calls that do not get retried forever). Note that serial transactions are -never return back to active transactions until the transaction has committed. -Likewise, active transactions stay active until they have committed. -Per-method-group locks are typically also not released before commit. - -Lock acquisition / blocking rules: - -* Transactions must become active or serial before they are allowed to - use method-group-specific locks or blocking (i.e., the serial lock must be - acquired before those other locks, either in serial or nonserial mode). - -* Any number of threads that do not currently run active transactions can - block while trying to get the serial lock in exclusive mode. Note that active - transactions must not block when trying to upgrade to serial mode unless there - is no other transaction that is trying that (the latter is ensured by the - serial lock implementation. - -* Method groups must prevent deadlocks on their locks. In particular, they - must also be prepared for another active transaction that has acquired - method-group-specific locks but is blocked during an attempt to upgrade to - being a serial transaction. See below for details. - -* Serial transactions can acquire method-group-specific locks because there - will be no other active nor serial transaction. - -There is no single rule for per-method-group blocking because this depends on -when a TM method might acquire locks. If no active transaction can upgrade to -being a serial transaction after it has acquired per-method-group locks (e.g., -when those locks are only acquired during an attempt to commit), then the TM -method does not need to consider a potential deadlock due to serial mode. - -If there can be upgrades to serial mode after the acquisition of -per-method-group locks, then TM methods need to avoid those deadlocks: - -* When upgrading to a serial transaction, after acquiring exclusive rights - to the serial lock but before waiting for concurrent active transactions to - finish (see :ref:`serial-lock-impl` for details), - we have to wake up all active transactions waiting on the upgrader's - per-method-group locks. - -* Active transactions blocking on per-method-group locks need to check the - serial lock and abort if there is a pending serial transaction. - -* Lost wake-ups have to be prevented (e.g., by changing a bit in each - per-method-group lock before doing the wake-up, and only blocking on this lock - using a futex if this bit is not group). - -.. todo:: Can reuse serial lock for gl-\*? And if we can, does it make - sense to introduce further complexity in the serial lock? For gl-\*, we can - really only avoid an abort if we do -wb and -vbv. - -.. _serial-lock-impl: - -Serial lock implementation -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The serial lock implementation is optimized towards assuming that serial -transactions are infrequent and not the common case. However, the performance -of entering serial mode can matter because when only few transactions are run -concurrently or if there are few threads, then it can be efficient to run -transactions serially. - -The serial lock is similar to a multi-reader-single-writer lock in that there -can be several active transactions but only one serial transaction. However, -we do want to avoid contention (in the lock implementation) between active -transactions, so we split up the reader side of the lock into per-transaction -flags that are true iff the transaction is active. The exclusive writer side -remains a shared single flag, which is acquired using a CAS, for example. -On the fast-path, the serial lock then works similar to Dekker's algorithm but -with several reader flags that a serial transaction would have to check. -A serial transaction thus requires a list of all threads with potentially -active transactions; we can use the serial lock itself to protect this list -(i.e., only threads that have acquired the serial lock can modify this list). - -We want starvation-freedom for the serial lock to allow for using it to ensure -progress for potentially starved transactions (see :ref:`progress-guarantees` for details). However, this is currently not enforced by -the implementation of the serial lock. - -Here is pseudo-code for the read/write fast paths of acquiring the serial -lock (read-to-write upgrade is similar to write_lock: - -.. code-block:: c++ - - // read_lock: - tx->shared_state |= active; - __sync_synchronize(); // or STLD membar, or C++0x seq-cst fence - while (!serial_lock.exclusive) - if (spinning_for_too_long) goto slowpath; - - // write_lock: - if (CAS(&serial_lock.exclusive, 0, this) != 0) - goto slowpath; // writer-writer contention - // need a membar here, but CAS already has full membar semantics - bool need_blocking = false; - for (t: all txns) - { - for (;t->shared_state & active;) - if (spinning_for_too_long) { need_blocking = true; break; } - } - if (need_blocking) goto slowpath; - -Releasing a lock in this spin-lock version then just consists of resetting -``tx->shared_state`` to inactive or clearing ``serial_lock.exclusive``. - -However, we can't rely on a pure spinlock because we need to get the OS -involved at some time (e.g., when there are more threads than CPUs to run on). -Therefore, the real implementation falls back to a blocking slow path, either -based on pthread mutexes or Linux futexes. - -Reentrancy -^^^^^^^^^^ - -libitm has to consider the following cases of reentrancy: - -* Transaction calls unsafe code that starts a new transaction: The outer - transaction will become a serial transaction before executing unsafe code. - Therefore, nesting within serial transactions must work, even if the nested - transaction is called from within uninstrumented code. - -* Transaction calls either a transactional wrapper or safe code, which in - turn starts a new transaction: It is not yet defined in the specification - whether this is allowed. Thus, it is undefined whether libitm supports this. - -* Code that starts new transactions might be called from within any part - of libitm: This kind of reentrancy would likely be rather complex and can - probably be avoided. Therefore, it is not supported. - -Privatization safety -^^^^^^^^^^^^^^^^^^^^ - -Privatization safety is ensured by libitm using a quiescence-based approach. -Basically, a privatizing transaction waits until all concurrent active -transactions will either have finished (are not active anymore) or operate on -a sufficiently recent snapshot to not access the privatized data anymore. This -happens after the privatizing transaction has stopped being an active -transaction, so waiting for quiescence does not contribute to deadlocks. - -In method groups that need to ensure publication safety explicitly, active -transactions maintain a flag or timestamp in the public/shared part of the -transaction descriptor. Before blocking, privatizers need to let the other -transactions know that they should wake up the privatizer. - -.. todo:: How to implement the waiters? Should those flags be - per-transaction or at a central place? We want to avoid one wake/wait call - per active transactions, so we might want to use either a tree or combining - to reduce the syscall overhead, or rather spin for a long amount of time - instead of doing blocking. Also, it would be good if only the last transaction - that the privatizer waits for would do the wake-up. - -.. _progress-guarantees: - -Progress guarantees -^^^^^^^^^^^^^^^^^^^ - -Transactions that do not make progress when using the current TM method will -eventually try to execute in serial mode. Thus, the serial lock's progress -guarantees determine the progress guarantees of the whole TM. Obviously, we at -least need deadlock-freedom for the serial lock, but it would also be good to -provide starvation-freedom (informally, all threads will finish executing a -transaction eventually iff they get enough cycles). - -However, the scheduling of transactions (e.g., thread scheduling by the OS) -also affects the handling of progress guarantees by the TM. First, the TM -can only guarantee deadlock-freedom if threads do not get stopped. Likewise, -low-priority threads can starve if they do not get scheduled when other -high-priority threads get those cycles instead. - -If all threads get scheduled eventually, correct lock implementations will -provide deadlock-freedom, but might not provide starvation-freedom. We can -either enforce the latter in the TM's lock implementation, or assume that -the scheduling is sufficiently random to yield a probabilistic guarantee that -no thread will starve (because eventually, a transaction will encounter a -scheduling that will allow it to run). This can indeed work well in practice -but is not necessarily guaranteed to work (e.g., simple spin locks can be -pretty efficient). - -Because enforcing stronger progress guarantees in the TM has a higher runtime -overhead, we focus on deadlock-freedom right now and assume that the threads -will get scheduled eventually by the OS (but don't consider threads with -different priorities). We should support starvation-freedom for serial -transactions in the future. Everything beyond that is highly related to proper -contention management across all of the TM (including with TM method to -choose), and is future work. - -**TODO** Handling thread priorities: We want to avoid priority inversion -but it's unclear how often that actually matters in practice. Workloads that -have threads with different priorities will likely also require lower latency -or higher throughput for high-priority threads. Therefore, it probably makes -not that much sense (except for eventual progress guarantees) to use -priority inheritance until the TM has priority-aware contention management.
\ No newline at end of file diff --git a/libitm/doc/nesting-flat-vs-closed.rst b/libitm/doc/nesting-flat-vs-closed.rst deleted file mode 100644 index 8b157baed98..00000000000 --- a/libitm/doc/nesting-flat-vs-closed.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -Nesting: flat vs. closed -************************ - -We support two different kinds of nesting of transactions. In the case of -*flat nesting*, the nesting structure is flattened and all nested -transactions are subsumed by the enclosing transaction. In contrast, -with *closed nesting*, nested transactions that have not yet committed -can be rolled back separately from the enclosing transactions; when they -commit, they are subsumed by the enclosing transaction, and their effects -will be finally committed when the outermost transaction commits. -*Open nesting* (where nested transactions can commit independently of the -enclosing transactions) are not supported. - -Flat nesting is the default nesting mode, but closed nesting is supported and -used when transactions contain user-controlled aborts -(``__transaction_cancel`` statements). We assume that user-controlled -aborts are rare in typical code and used mostly in exceptional situations. -Thus, it makes more sense to use flat nesting by default to avoid the -performance overhead of the additional checkpoints required for closed -nesting. User-controlled aborts will correctly abort the innermost enclosing -transaction, whereas the whole (i.e., outermost) transaction will be restarted -otherwise (e.g., when a transaction encounters data conflicts during -optimistic execution).
\ No newline at end of file diff --git a/libitm/doc/the-libitm-abi.rst b/libitm/doc/the-libitm-abi.rst deleted file mode 100644 index 2340074a4f6..00000000000 --- a/libitm/doc/the-libitm-abi.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. _the-libitm-abi: - -The libitm ABI --------------- - -The ABI provided by libitm is basically equal to the Linux variant of Intel's -current TM ABI specification document (Revision 1.1, May 6 2009) but with the -differences listed in this chapter. It would be good if these changes would -eventually be merged into a future version of this specification. To ease -look-up, the following subsections mirror the structure of this specification. - -.. toctree:: - :maxdepth: 2 - - the-libitm-abi/objectives - the-libitm-abi/non-objectives - the-libitm-abi/library-design-principles - the-libitm-abi/types-and-macros-list - the-libitm-abi/function-list - the-libitm-abi/future-enhancements-to-the-abi - the-libitm-abi/sample-code - the-libitm-abi/memory-model
\ No newline at end of file diff --git a/libitm/doc/the-libitm-abi/function-list.rst b/libitm/doc/the-libitm-abi/function-list.rst deleted file mode 100644 index 79cc5d820e5..00000000000 --- a/libitm/doc/the-libitm-abi/function-list.rst +++ /dev/null @@ -1,272 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -Function list -************* - -Initialization and finalization functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -These functions are not part of the ABI. - -[No changes] Version checking -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -[No changes] Error reporting -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -[No changes] inTransaction call -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -State manipulation functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -There is no ``getTransaction`` function. Transaction identifiers for -nested transactions will be ordered but not necessarily sequential (i.e., for -a nested transaction's identifier :samp:`{IN}` and its enclosing transaction's -identifier :samp:`{IE}`, it is guaranteed that IN >= IE). - -[No changes] Source locations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Starting a transaction -^^^^^^^^^^^^^^^^^^^^^^ - -.. _txn-code-properties: - -Transaction code properties -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The bit ``hasNoXMMUpdate`` is instead called ``hasNoVectorUpdate``. -Iff it is set, vector register save/restore is not necessary for any target -machine. - -The ``hasNoFloatUpdate`` bit (``0x0010``) is new. Iff it is set, floating -point register save/restore is not necessary for any target machine. - -``undoLogCode`` is not supported and a fatal runtime error will be raised -if this bit is set. It is not properly defined in the ABI why barriers -other than undo logging are not present; Are they not necessary (e.g., a -transaction operating purely on thread-local data) or have they been omitted by -the compiler because it thinks that some kind of global synchronization -(e.g., serial mode) might perform better? The specification suggests that the -latter might be the case, but the former seems to be more useful. - -The ``readOnly`` bit (``0x4000``) is new. - -.. todo:: Lexical or dynamic scope? - -``hasNoRetry`` is not supported. If this bit is not set, but -``hasNoAbort`` is set, the library can assume that transaction -rollback will not be requested. - -It would be useful if the absence of externally-triggered rollbacks would be -reported for the dynamic scope as well, not just for the lexical scope -(``hasNoAbort``). Without this, a library cannot exploit this together -with flat nesting. - -``exceptionBlock`` is not supported because exception blocks are not used. - -[No changes] Windows exception state -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -[No changes] Other machine state -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -[No changes] Results from beginTransaction -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Aborting a transaction -^^^^^^^^^^^^^^^^^^^^^^ - -``_ITM_rollbackTransaction`` is not supported. ``_ITM_abortTransaction`` -is supported but the abort reasons ``exceptionBlockAbort``, -``TMConflict``, and ``userRetry`` are not supported. There are no -exception blocks in general, so the related cases also do not have to be -considered. To encode ``__transaction_cancel [[outer]]``, compilers must -set the new ``outerAbort`` bit (``0x10``) additionally to the -``userAbort`` bit in the abort reason. - -Committing a transaction -^^^^^^^^^^^^^^^^^^^^^^^^ - -The exception handling (EH) scheme is different. The Intel ABI requires the -``_ITM_tryCommitTransaction`` function that will return even when the -commit failed and will have to be matched with calls to either -``_ITM_abortTransaction`` or ``_ITM_commitTransaction``. In contrast, -gcc relies on transactional wrappers for the functions of the Exception -Handling ABI and on one additional commit function (shown below). This allows -the TM to keep track of EH internally and thus it does not have to embed the -cleanup of EH state into the existing EH code in the program. -``_ITM_tryCommitTransaction`` is not supported. -``_ITM_commitTransactionToId`` is also not supported because the -propagation of thrown exceptions will not bypass commits of nested -transactions. - -.. code-block:: c++ - - void _ITM_commitTransactionEH(void *exc_ptr) ITM_REGPARM; - void *_ITM_cxa_allocate_exception (size_t); - void _ITM_cxa_free_exception (void *exc_ptr); - void _ITM_cxa_throw (void *obj, void *tinfo, void (*dest) (void *)); - void *_ITM_cxa_begin_catch (void *exc_ptr); - void _ITM_cxa_end_catch (void); - -The EH scheme changed in version 6 of GCC. Previously, the compiler -added a call to ``_ITM_commitTransactionEH`` to commit a transaction if -an exception could be in flight at this position in the code; ``exc_ptr`` is -the address of the current exception and must be non-zero. Now, the -compiler must catch all exceptions that are about to be thrown out of a -transaction and call ``_ITM_commitTransactionEH`` from the catch clause, -with ``exc_ptr`` being zero. - -Note that the old EH scheme never worked completely in GCC's implementation; -libitm currently does not try to be compatible with the old scheme. - -The ``_ITM_cxa...`` functions are transactional wrappers for the respective -``__cxa...`` functions and must be called instead of these in transactional -code. ``_ITM_cxa_free_exception`` is new in GCC 6. - -To support this EH scheme, libstdc++ needs to provide one additional function -(``_cxa_tm_cleanup``), which is used by the TM to clean up the exception -handling state while rolling back a transaction: - -.. code-block:: c++ - - void __cxa_tm_cleanup (void *unthrown_obj, void *cleanup_exc, - unsigned int caught_count); - -Since GCC 6, ``unthrown_obj`` is not used anymore and always null; -prior to that, ``unthrown_obj`` is non-null if the program called -``__cxa_allocate_exception`` for this exception but did not yet called -``__cxa_throw`` for it. ``cleanup_exc`` is non-null if the program is -currently processing a cleanup along an exception path but has not caught this -exception yet. ``caught_count`` is the nesting depth of -``__cxa_begin_catch`` within the transaction (which can be counted by the TM -using ``_ITM_cxa_begin_catch`` and ``_ITM_cxa_end_catch``); -``__cxa_tm_cleanup`` then performs rollback by essentially performing -``__cxa_end_catch`` that many times. - -Exception handling support -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Currently, there is no support for functionality like -``__transaction_cancel throw`` as described in the C++ TM specification. -Supporting this should be possible with the EH scheme explained previously -because via the transactional wrappers for the EH ABI, the TM is able to -observe and intercept EH. - -[No changes] Transition to serial--irrevocable mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -[No changes] Data transfer functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -[No changes] Transactional memory copies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Transactional versions of memmove -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If either the source or destination memory region is to be accessed -nontransactionally, then source and destination regions must not be -overlapping. The respective ``_ITM_memmove`` functions are still -available but a fatal runtime error will be raised if such regions do overlap. -To support this functionality, the ABI would have to specify how the -intersection of the regions has to be accessed (i.e., transactionally or -nontransactionally). - -[No changes] Transactional versions of memset -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -[No changes] Logging functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -User-registered commit and undo actions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Commit actions will get executed in the same order in which the respective -calls to ``_ITM_addUserCommitAction`` happened. Only -``_ITM_noTransactionId`` is allowed as value for the -``resumingTransactionId`` argument. Commit actions get executed after -privatization safety has been ensured. - -Undo actions will get executed in reverse order compared to the order in which -the respective calls to ``_ITM_addUserUndoAction`` happened. The ordering of -undo actions w.r.t. the roll-back of other actions (e.g., data transfers or -memory allocations) is undefined. - -``_ITM_getThreadnum`` is not supported currently because its only purpose -is to provide a thread ID that matches some assumed performance tuning output, -but this output is not part of the ABI nor further defined by it. - -``_ITM_dropReferences`` is not supported currently because its semantics and -the intention behind it is not entirely clear. The -specification suggests that this function is necessary because of certain -orderings of data transfer undos and the releasing of memory regions (i.e., -privatization). However, this ordering is never defined, nor is the ordering of -dropping references w.r.t. other events. - -[New] Transactional indirect calls -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Indirect calls (i.e., calls through a function pointer) within transactions -should execute the transactional clone of the original function (i.e., a clone -of the original that has been fully instrumented to use the TM runtime), if -such a clone is available. The runtime provides two functions to -register/deregister clone tables: - -.. code-block:: c++ - - struct clone_entry - { - void *orig, *clone; - }; - - void _ITM_registerTMCloneTable (clone_entry *table, size_t entries); - void _ITM_deregisterTMCloneTable (clone_entry *table); - -Registered tables must be writable by the TM runtime, and must be live -throughout the life-time of the TM runtime. - -.. todo:: The intention was always to drop the registration functions - entirely, and create a new ELF Phdr describing the linker-sorted table. Much - like what currently happens for ``PT_GNU_EH_FRAME``. - This work kept getting bogged down in how to represent the :samp:`{N}` different - code generation variants. We clearly needed at least two---SW and HW - transactional clones---but there was always a suggestion of more variants for - different TM assumptions/invariants. - -The compiler can then use two TM runtime functions to perform indirect calls in -transactions: - -.. code-block:: c++ - - void *_ITM_getTMCloneOrIrrevocable (void *function) ITM_REGPARM; - void *_ITM_getTMCloneSafe (void *function) ITM_REGPARM; - -If there is a registered clone for supplied function, both will return a -pointer to the clone. If not, the first runtime function will attempt to switch -to serial--irrevocable mode and return the original pointer, whereas the second -will raise a fatal runtime error. - -[New] Transactional dynamic memory management -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: c++ - - void *_ITM_malloc (size_t) - __attribute__((__malloc__)) ITM_PURE; - void *_ITM_calloc (size_t, size_t) - __attribute__((__malloc__)) ITM_PURE; - void _ITM_free (void *) ITM_PURE; - -These functions are essentially transactional wrappers for ``malloc``, -``calloc``, and ``free``. Within transactions, the compiler should -replace calls to the original functions with calls to the wrapper functions. - -libitm also provides transactional clones of C++ memory management functions -such as global operator new and delete. They are part of libitm for historic -reasons but do not need to be part of this ABI.
\ No newline at end of file diff --git a/libitm/doc/the-libitm-abi/future-enhancements-to-the-abi.rst b/libitm/doc/the-libitm-abi/future-enhancements-to-the-abi.rst deleted file mode 100644 index f8fbac355e0..00000000000 --- a/libitm/doc/the-libitm-abi/future-enhancements-to-the-abi.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -[No changes] Future Enhancements to the ABI -*******************************************
\ No newline at end of file diff --git a/libitm/doc/the-libitm-abi/library-design-principles.rst b/libitm/doc/the-libitm-abi/library-design-principles.rst deleted file mode 100644 index 7482994f2b1..00000000000 --- a/libitm/doc/the-libitm-abi/library-design-principles.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -Library design principles -************************* - -[No changes] Calling conventions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -[No changes] TM library algorithms -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -[No changes] Optimized load and store routines -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -[No changes] Aligned load and store routines -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Data logging functions -^^^^^^^^^^^^^^^^^^^^^^ - -The memory locations accessed with transactional loads and stores and the -memory locations whose values are logged must not overlap. This required -separation only extends to the scope of the execution of one transaction -including all the executions of all nested transactions. - -The compiler must be consistent (within the scope of a single transaction) -about which memory locations are shared and which are not shared with other -threads (i.e., data must be accessed either transactionally or -nontransactionally). Otherwise, non-write-through TM algorithms would not work. - -For memory locations on the stack, this requirement extends to only the -lifetime of the stack frame that the memory location belongs to (or the -lifetime of the transaction, whichever is shorter). Thus, memory that is -reused for several stack frames could be target of both data logging and -transactional accesses; however, this is harmless because these stack frames' -lifetimes will end before the transaction finishes. - -[No changes] Scatter/gather calls -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -[No changes] Serial and irrevocable mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -[No changes] Transaction descriptor -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Store allocation -^^^^^^^^^^^^^^^^ - -There is no ``getTransaction`` function. - -[No changes] Naming conventions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Function pointer encryption -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Currently, this is not implemented.
\ No newline at end of file diff --git a/libitm/doc/the-libitm-abi/memory-model.rst b/libitm/doc/the-libitm-abi/memory-model.rst deleted file mode 100644 index f43e2f81df5..00000000000 --- a/libitm/doc/the-libitm-abi/memory-model.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -[New] Memory model -****************** - -The ABI should define a memory model and the ordering that is guaranteed for -data transfers and commit/undo actions, or at least refer to another memory -model that needs to be preserved. Without that, the compiler cannot ensure the -memory model specified on the level of the programming language (e.g., by the -C++ TM specification). - -For example, if a transactional load is ordered before another load/store, then -the TM runtime must also ensure this ordering when accessing shared state. If -not, this might break the kind of publication safety used in the C++ TM -specification. Likewise, the TM runtime must ensure privatization safety.
\ No newline at end of file diff --git a/libitm/doc/the-libitm-abi/non-objectives.rst b/libitm/doc/the-libitm-abi/non-objectives.rst deleted file mode 100644 index b3c558e2394..00000000000 --- a/libitm/doc/the-libitm-abi/non-objectives.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -[No changes] Non-objectives -***************************
\ No newline at end of file diff --git a/libitm/doc/the-libitm-abi/objectives.rst b/libitm/doc/the-libitm-abi/objectives.rst deleted file mode 100644 index d4c5d460041..00000000000 --- a/libitm/doc/the-libitm-abi/objectives.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -[No changes] Objectives -***********************
\ No newline at end of file diff --git a/libitm/doc/the-libitm-abi/sample-code.rst b/libitm/doc/the-libitm-abi/sample-code.rst deleted file mode 100644 index c8e9541d810..00000000000 --- a/libitm/doc/the-libitm-abi/sample-code.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -Sample code -************ - -The code examples might not be correct w.r.t. the current version of the ABI, -especially everything related to exception handling.
\ No newline at end of file diff --git a/libitm/doc/the-libitm-abi/types-and-macros-list.rst b/libitm/doc/the-libitm-abi/types-and-macros-list.rst deleted file mode 100644 index 248c6666497..00000000000 --- a/libitm/doc/the-libitm-abi/types-and-macros-list.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -Types and macros list -********************* - -``_ITM_codeProperties`` has changed, see :ref:`txn-code-properties`. -``_ITM_srcLocation`` is not used.
\ No newline at end of file diff --git a/libitm/doc/tm-methods-and-method-groups.rst b/libitm/doc/tm-methods-and-method-groups.rst deleted file mode 100644 index a9b56197a5b..00000000000 --- a/libitm/doc/tm-methods-and-method-groups.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -TM methods and method groups -**************************** - -libitm supports several ways of synchronizing transactions with each other. -These TM methods (or TM algorithms) are implemented in the form of -subclasses of ``abi_dispatch``, which provide methods for -transactional loads and stores as well as callbacks for rollback and commit. -All methods that are compatible with each other (i.e., that let concurrently -running transactions still synchronize correctly even if different methods -are used) belong to the same TM method group. Pointers to TM methods can be -obtained using the factory methods prefixed with ``dispatch_`` in -:samp:`libitm_i.h`. There are two special methods, ``dispatch_serial`` and -``dispatch_serialirr``, that are compatible with all methods because they -run transactions completely in serial mode. - -TM method life cycle -^^^^^^^^^^^^^^^^^^^^ - -The state of TM methods does not change after construction, but they do alter -the state of transactions that use this method. However, because -per-transaction data gets used by several methods, ``gtm_thread`` is -responsible for setting an initial state that is useful for all methods. -After that, methods are responsible for resetting/clearing this state on each -rollback or commit (of outermost transactions), so that the transaction -executed next is not affected by the previous transaction. - -There is also global state associated with each method group, which is -initialized and shut down (``method_group::init()`` and ``fini()``) -when switching between method groups (see :samp:`retry.cc`). - -Selecting the default method -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The default method that libitm uses for freshly started transactions (but -not necessarily for restarted transactions) can be set via an environment -variable (:envvar:`ITM_DEFAULT_METHOD`), whose value should be equal to the name -of one of the factory methods returning abi_dispatch subclasses but without -the "dispatch\_" prefix (e.g., "serialirr" instead of -``GTM::dispatch_serialirr()``). - -Note that this environment variable is only a hint for libitm and might not -be supported in the future.
\ No newline at end of file |