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

From: Andi Kleen
Date: Fri Mar 22 2013 - 21:26:40 EST

From: Andi Kleen <ak@xxxxxxxxxxxxxxx>

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

Signed-off-by: Andi Kleen <ak@xxxxxxxxxxxxxxx>
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
+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
+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.
+"Adding Lock elision to Linux"
+"Adding lock elision to the GNU C Library"
+Full TSX specification:
+http://software.intel.com/file/41417 (chapter 8)
+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

To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/