[PATCH] Document HLE metadata

[Michael Liao]

Hi Jeff

On Wed, 2013-02-27 at 14:22 -0800, Jeffrey Yasskin wrote:
> 
> ================
> 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.

The execution here only refer to the atomic ops on the atomic variable.
The description here is to address two possible states after this atomic
ins, i.e. either in transactional state or not.

> 
> 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.

I assume people have the basic knowledge of implementing lock upon
atomic builtins, like paring acquire and release on the same atomic
variable and setting back its original state when unlocking. Putting
them here definitely won't hurt but may be verbose.

I don't understand the point 3. Could you put more details on that?

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

Sure, I will add sentence to on this. All hint should not break
correctness if not properly used.

> 
> 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.

We could refer other TM supported hardware here if people want to ensure
it should not be a target specific feature.

> <<<<<<<<<<<<<<<<
> 
> 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.

My understanding is that we have no way to put a nil metanode
(setMetadata()). Correct me if my understanding is wrong.

- michael

> 
> 
> http://llvm-reviews.chandlerc.com/D475
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits