[llvm] r351772 - [LangRef] Clarify semantics of volatile operations.

[Eli Friedman via llvm-commits]

Author: efriedma
Date: Mon Jan 21 16:42:20 2019
New Revision: 351772

URL: http://llvm.org/viewvc/llvm-project?rev=351772&view=rev
Log:
[LangRef] Clarify semantics of volatile operations.

Specifically, clarify the following:

1. Volatile load and store may access addresses that are not memory.
2. Volatile load and store do not modify arbitrary memory.
3. Volatile load and store do not trap.

Prompted by recent volatile discussion on llvmdev.

Currently, there's sort of a split in the source code about whether
volatile operations are allowed to trap; this resolves that dispute in
favor of not allowing them to trap.

Differential Revision: https://reviews.llvm.org/D53184


Modified:
    llvm/trunk/docs/LangRef.rst

Modified: llvm/trunk/docs/LangRef.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/LangRef.rst?rev=351772&r1=351771&r2=351772&view=diff
==============================================================================
--- llvm/trunk/docs/LangRef.rst (original)
+++ llvm/trunk/docs/LangRef.rst Mon Jan 21 16:42:20 2019
@@ -2181,6 +2181,24 @@ volatile operations. The optimizers *may
 operations relative to non-volatile operations. This is not Java's
 "volatile" and has no cross-thread synchronization behavior.
 
+A volatile load or store may have additional target-specific semantics.
+Any volatile operation can have side effects, and any volatile operation
+can read and/or modify state which is not accessible via a regular load
+or store in this module. Volatile operations may use adresses which do
+not point to memory (like MMIO registers). This means the compiler may
+not use a volatile operation to prove a non-volatile access to that
+address has defined behavior.
+
+The allowed side-effects for volatile accesses are limited.  If a
+non-volatile store to a given address would be legal, a volatile
+operation may modify the memory at that address. A volatile operation
+may not modify any other memory accessible by the module being compiled.
+A volatile operation may not call any code in the current module.
+
+The compiler may assume execution will continue after a volatile operation,
+so operations which modify memory or may have undefined behavior can be
+hoisted past a volatile operation.
+
 IR-level volatile loads and stores cannot safely be optimized into
 llvm.memcpy or llvm.memmove intrinsics even when those intrinsics are
 flagged volatile. Likewise, the backend should never split or merge