[PATCH] Document HLE metadata

[darkbuck]

  Hi All

  Here is the revised document adding rationale and re-phrasing the HLE semantics.

  Thanks for review.
  - Michael

Hi eli.friedman, chandlerc, jyasskin, nadav, hfinkel,

http://llvm-reviews.chandlerc.com/D475

CHANGE SINCE LAST DIFF
  http://llvm-reviews.chandlerc.com/D475?vs=1137&id=1318#toc

Files:
  docs/LangRef.rst

Index: docs/LangRef.rst
===================================================================
--- docs/LangRef.rst
+++ docs/LangRef.rst
@@ -1292,6 +1292,43 @@
 other operations running in the same thread (for example, in signal
 handlers).
 
+Hardware Lock Elision Hint
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. admonition:: Rationale
+
+  As lock primitives are built upon atomic instructions, HLE hints attached on
+  atomic instructions allow programmers to convert a locked-based critical
+  section into a transaction region to take advantage of hardware transactional
+  memory support in certain targets, e.g. `Intel X86 processors post-Haswell
+  <http://en.wikipedia.org/wiki/Transactional_Synchronization_Extensions>`_. At
+  the same time, a hinted atomic instruction is still an atomic instruction and
+  will execute as if it's not hinted.
+
+Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`, :ref:`atomicrmw <i_atomicrmw>`,
+and :ref:`atomic store <i_store>`) may take an optional hint of Hardware Lock
+Elision (Speculative Lock Elision or Transactional Lock Elision) to start an
+HLEd critical section by hinting an atomic instruction with HLE *acquire* hint
+and to end an end an HLEd critical section by hinting an atomic instruction
+with HLE *release* hint.
+
+With an HLE *acquire* hint, an atomic instruction is executed speculatively on
+the specified atomic object. It also start the transactional execution until
+a matching atomic instruction with an HLE *release* hint.
+
+With an HLE *release* hint, an atomic instruction ends the transactional
+execution started by a matching atomic instruction with an HLE *acquire* hint.
+It tries to commit the changes to shared memory, which is not global visible
+before a sucessful commit. If the commit fails, the execution will be restarted
+from the point where an early atomic instruction hinted with HLE *acquire*.
+
+It's expected that HLE hints are paired similar to lock/unlock usage in thread
+synchronization. However, improper use of HLE hints will not cause functional
+issues.
+
+See :ref:`hle.lock metadata <hle_hint>` for details on adding HLE hint on
+atomic instructions.
+
 .. _fastmath:
 
 Fast-Math Flags
@@ -2644,6 +2681,35 @@
    !1 = metadata !{ metadata !1 } ; an identifier for the inner parallel loop
    !2 = metadata !{ metadata !2 } ; an identifier for the outer parallel loop
 
+.. _hle_hint:
+
+'``hle.lock``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``hle.lock`` metadata may be attached only to an atomic instruction. It
+presents the Hardware Lock Elision (HLE) hint to the backend. The hint is
+represented as a metadata string of either ``acquire`` or ``release``.
+
+``acquire``
+  ``acquire`` is a hint to start lock elision on the memory address specified
+  by the atomic instruction.
+
+``release``
+  ``release`` is a hint to end lock elision on the memory address specified by
+  the atomic instruction.
+
+If a target does not support HLE, the backend should ignore such these hints.
+
+Examples:
+
+.. code-block:: llvm
+
+      %t4 = cmpxchg i32* @sc32, i32 0, i32 1 acquire, !hle.lock !0
+      store atomic i32 0, i32* @sc32 release, !hle.lock !1
+    ...
+    !0 = metadata !{metadata !"acquire"}
+    !1 = metadata !{metadata !"release"}
+
 
 Module Flags Metadata
 =====================
-------------- next part --------------
A non-text attachment was scrubbed...
Name: D475.2.patch
Type: text/x-patch
Size: 3292 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20130319/72c6b38d/attachment.bin>