[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

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@351772 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/docs/LangRef.rst b/docs/LangRef.rst
index 0843bf503d054087b782b7d5ace7f2dfd5bbc45c..9168648db6e22adb9b765a931aa32bc8742888f7 100644 (file)
--- a/docs/LangRef.rst
+++ b/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