[PATCH 29/29] tsx: Add documentation for lock-elision

Andi Kleen
2013-03-23T01:26:20Z

Document the tunables and the statistics in Documentation/lock-elision.txt

Signed-off-by: Andi Kleen <ak@linux.intel.com>
---
Documentation/lock-elision.txt | 94 ++++++++++++++++++++++++++++++++++++++++
1 files changed, 94 insertions(+), 0 deletions(-)
create mode 100644 Documentation/lock-elision.txt

diff --git a/Documentation/lock-elision.txt b/Documentation/lock-elision.txt
new file mode 100644
index 0000000..bc5a5ac
--- /dev/null
+++ b/Documentation/lock-elision.txt
@@ -0,0 +1,94 @@
+
+The Linux kernel uses Intel TSX lock elision for most of its locking primitives,
+when the hardware supports TSX.
+
+This allows to run lock regions that follow specific conditions to run
+in parallel without explicit blocking in a memory transaction. If the
+transaction fails the code falls back to the normal lock.
+
+The lock elision is implemented using RTM.
+
+To measure transaction success the TSX perf extensions should be used.
+(At the time of this writing this requires unmerged perf patches,
+as in the full Haswell PMU patch series in hsw/pmu* in
+git://git.kernel.org/pub/scm/linux/kernel/git/ak/linux-misc.git)
+
+perf stat -T ...
+perf record -e tx-aborts ...
+
+The elision code is mostly adaptive, that is the lock predicts whether
+it should elide or not based on the history.
+
+There are various tunables available in /sys/module/rtm_locks/parameters.
+The tunables are grouped by lock types.
+
+Elision can be enabled by lock types:
+
+rwsem_elision Enable elision for read-write semaphores
+mutex_elision Enable elision for mutexes
+spinlock_elision Enable elision for spinlocks
+rwlock_elision Enable elision for read-write spinlocks
+bitlock_elision Enable elision for bit spinlocks
+
+Some lock types use adaptive algorithms. The adaptive algorithm
+has a number of tunables which can be tuned. Each tunable
+is named LOCKTYPE_TUNABLE. For example to tune the conflict retries
+for mutexes do
+
+echo NUMBER > /sys/module/rtm_locks/parameters/mutex_conflict_retry
+
+Valid adaptive lock types are:
+mutex, readlock, writelock, readsem, writesem, spinlock
+
+The current tunables are (subject to change):
+
+In general increasing the skip counts makes lock elision more conservative,
+while increasing retries or timeout makes it more aggressive.
+
+*_elision Global elision enable for the lock type.
+*_conflict_abort_skip Number of elisions to skip when a transaction
+ failed due to a number of retried conflicts.
+*_conflict_retry Number of retries on memory conflicts
+*_internal_abort_skip Number of elision to skip when a transaction
+ failed due to a reason inside the transaction
+ (that is not caused by another CPU)
+*_lock_busy_retry How often to retry wen the lock is busy on
+ elision.
+*_lock_busy_skip How often to skip elision when retries on
+ lock busy failed.
+*_other_abort_skip How often to skip elision when the transaction
+ failed for other reasons (e.g. capacity overflow)
+*_retry_timeout How often to spin while waiting for a lock to free
+ before retrying
+
+Note these tunables do not present an ABI and may change as the internals
+evolve.
+
+Additional statistics:
+
+lock_el_skip Number of times a lock didn't elide due to skipping
+lock_el_skip_start Number of times a lock started skipping
+
+The average skip is lock_el_skip / lock_el_start_skip
+Additional statistics can be gotten using perf PMU TSX events.
+
+There is also a elision:elision_skip_start trace point that triggers every time
+a lock starts skipping elision due to non success.
+
+References:
+"Adding Lock elision to Linux"
+http://halobates.de/adding-lock-elision-to-linux.pdf
+
+"Adding lock elision to the GNU C Library"
+http://lwn.net/Articles/533894/
+
+Full TSX specification:
+http://software.intel.com/file/41417 (chapter 8)
+
+Glossary:
+cache line Aligned 64 byte region
+conflict Another CPU writes to a cache line read in a elided lock region,
+ or reads from a cache line written to in the region.
+abort Rolling back the transaction and undoing its side effect
+
+Andi Kleen
--
1.7.7.6