[PATCH] Document HLE metadata

[Jeffrey Yasskin]

================
Comment at: docs/LangRef.rst:1299
@@ +1298,3 @@
+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
----------------
spelling: Hareware

================
Comment at: docs/LangRef.rst:1304
@@ +1303,3 @@
+
+To *acquire* an elided lock, the target tries its best to execute speculatively
+on the specified atomic variable without assuming any semantic knowledge of
----------------
The langref needs to describe this in terms of an assertion about program behavior, not in terms of the hardware implementation. "Execute speculatively on a variable" doesn't mean anything to me since generally programs do not execute "on" variables.

For example, one plausible explanation might be:

>>>>>>>>>>>>>
The '!hle.lock !"acquire"' metadata on an atomic instruction that modifies a variable hints that
1) The variable is likely to be shared with other threads.
2) The next atomic instruction annotated with '!hle.lock' is likely to be annotated with '!hle.lock !"release"', operate on the same address and type, and set it back to its original value.
3) Intervening instructions are likely to be only memory operations with no non-memory side effects.

If the hints are violated, the program must still execute as if the !hle.lock metadata were not present.

Certain targets (e.g. <a href="http://en.wikipedia.org/wiki/Transactional_Synchronization_Extensions">Intel x86 processors post-Haswell</a>) can take advantage of this hint by speculatively skipping the write, recording memory operations until the matching release, and applying the batch atomically if the hints were accurate and no other thread conflicted with the operations, or restarting the whole sequence at the acquire-annotated instruction if a hint was violated or another thread modified an address accessed by this sequence.
<<<<<<<<<<<<<<<<

That explanation may not be correct, and people can probably improve the wording, but it's the style I'm looking for.

================
Comment at: docs/LangRef.rst:2680
@@ +2679,3 @@
+presents the Hardware Lock Elision (HLE) hint to the backend. The hint is
+represented as a metadata string of either ``acquire`` or ``release``.
+
----------------
I'd lean toward spelling these like !hle.lock.acquire and !hle.lock.release instead of requiring an extra string node, but I certainly won't insist if you or others prefer the string form.


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