[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 llvm-svn: 351772
llvm · Jan 22, 2019 · 9ba1682 · 9ba1682
1 parent b793d25
commit 9ba1682
Showing 1 changed file with 18 additions and 0 deletions.
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
@@ -2181,6 +2181,24 @@ volatile operations. The optimizers *may* change the order of volatile
 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