[PATCH] Document HLE metadata

[darkbuck]

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

Hi All,

I took the advice from Jeffrey to remove the target-specific metadata considering the IR portability among targets. Now, the proposal is adding HLE metadata (hle.lock) on atomic instructions to pass HLE hint (acquire or release). The documentation is revised first and semantic of a speculative atomic instruction is added within the context HLE and TM.

Thanks
- Michael


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

Files:
  docs/LangRef.rst

Index: docs/LangRef.rst
===================================================================
--- docs/LangRef.rst
+++ docs/LangRef.rst
@@ -1292,6 +1292,32 @@
 other operations running in the same thread (for example, in signal
 handlers).
 
+Hardware Lock Elision Hint
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`, :ref:`atomicrmw <i_atomicrmw>`,
+and :ref:`atomic store <i_store>`) may take an optional hint of Hareware Lock
+Elision (Speculative Lock Elision or Transactional Lock Elision) to start an
+HLEd critical section by *acquiring* an elided lock or end an HLEd
+critical section by *releasing* an elided lock.
+
+To *acquire* an elided lock, the target tries its best to execute speculatively
+on the specified atomic variable without assuming any semantic knowledge of
+that atomic variable. In other words, the target should not interpret the value
+of that atomic variable. Once the speculative execution is aborted, the target
+resumes the normal execution on that atomic variable.
+
+To *release* an elided lock, the target ends and commits the speculative
+execution if the specified atomic variable is previously *acquired*
+specutively. If that atomic variable is *acquired* in real, the target will
+*release* it by resuming the normal execution on that actomic variable. A
+target may choose to abort a speculative execution (or transaction) if the
+specified atomic variable cannot be restored to its original value it had just
+before the speculative *acquiring*.
+
+See :ref:`hle.lock metadata <hle_hint>` for details on adding HLE hint on
+atomic instructions.
+
 .. _fastmath:
 
 Fast-Math Flags
@@ -2644,6 +2670,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 a hint.
+
+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.1.patch
Type: text/x-patch
Size: 2759 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20130227/582f960d/attachment.bin>