[LangRef] Clarify semantics of masked vector load/store

[RalfJung]

This is based on what I think has to follow from the statement about preventing exceptions. But I don't actually know what LLVM IR passes will do with these intrinsics, so this requires careful review by someone who does. :)

@nikic do you know these passes / know who knows these passes to do the review?

Also, there's an open question that remains: for the purpose of noalias, do these operations access the masked-off lanes or not? I sure hope they don't, but I realized that while data races are mentioned, noalias is not.

[llvmbot]

@llvm/pr-subscribers-llvm-ir

Author: Ralf Jung (RalfJung)

Changes

This is based on what I think has to follow from the statement about preventing exceptions. But I don't actually know what LLVM IR passes will do with these intrinsics, so this requires careful review by someone who does. :)

@nikic do you know these passes / know who knows these passes to do the review?

Also, there's an open question that remains: for the purpose of noalias, do these operations access the masked-off lanes or not? I sure hope they don't, but I realized that while data races are mentioned, noalias is not.

---

Full diff: https://github.com/llvm/llvm-project/pull/82469.diff

1 Files Affected:

• (modified) llvm/docs/LangRef.rst (+2)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index fd2e3aacd0169c..496773c4d3d386 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -23752,6 +23752,7 @@ Semantics:
 
 The '``llvm.masked.load``' intrinsic is designed for conditional reading of selected vector elements in a single IR operation. It is useful for targets that support vector masked loads and allows vectorizing predicated basic blocks on these targets. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar load operations.
 The result of this operation is equivalent to a regular vector load instruction followed by a 'select' between the loaded and the passthru values, predicated on the same mask. However, using this intrinsic prevents exceptions on memory access to masked-off lanes.
+In particular, this means that only the masked-on lanes of the vector need to be inbounds of an allocation (but all these lanes need to be inbounds of the same allocation).
 
 
 ::
@@ -23794,6 +23795,7 @@ Semantics:
 
 The '``llvm.masked.store``' intrinsics is designed for conditional writing of selected vector elements in a single IR operation. It is useful for targets that support vector masked store and allows vectorizing predicated basic blocks on these targets. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar store operations.
 The result of this operation is equivalent to a load-modify-store sequence. However, using this intrinsic prevents exceptions and data races on memory access to masked-off lanes.
+In particular, this means that only the masked-on lanes of the vector need to be inbounds of an allocation (but all these lanes need to be inbounds of the same allocation).
 
 ::
 

[RalfJung]

Is "masked-on" the opposite of "masked-off"? Or is there some other term I could use?

[nikic]

I would rephrase this in terms of something like this:

However, these intrinsics behave as-is the masked off lanes are not accessed.

Which should tell use everything necessary about their semantics. Then can continue to clarify that this means no exceptions / data races / etc.

[RalfJung]

That doesn't quite say everything -- there's the question of whether this Rust PR should say offset (aka getelementptr inbounds) or offset_wrapping (aka getelementptr) when describing how the pointers to the individual elements being loaded are computed.

[programmerjake]

That doesn't quite say everything -- there's the question of whether this Rust PR should say offset (aka getelementptr inbounds)

there is the additional caveat that LLVM is allowed to create a poison value without UB (which is what happens with getelementptr inbounds with out-of-bounds indexes), but Rust defines out-of-bounds offset to be immediate UB, instead of deferred to the load/store.

a major difference between the two choices is that doing a masked load on a pointer before the beginning of it's allocation is disallowed with inbounds, but allowed without inbounds as long as vector elements are masked-off until the offset is big enough to be in the allocation's bounds.

[RalfJung]

a major difference between the two choices is that doing a masked load on a pointer before the beginning of it's allocation is disallowed with inbounds, but allowed without inbounds as long as vector elements are masked-off until the offset is big enough to be in the allocation's bounds.

Yes that is indeed the key point: if the first half of the vector is masked-off, and that first half is actually out-of-bounds, then the pointer itself is conceptually out-of-bounds and "computing the pointer to the actually loaded element" would be a non-inbounds pointer computation. I expect this usecase to be allowed, which is why I added the following in this PR:

Only the masked-on lanes of the vector need to be inbounds of an allocation (but all these lanes need to be inbounds of the same allocation).

[RalfJung]

@nikic I have updated the wording to

The result of this operation is equivalent to a regular vector load instruction followed by a 'select' between the loaded and the passthru values, predicated on the same mask, except that the masked-off lanes are not accessed.

Followed by clarification regarding exceptions, noalias, and data races. Does that work for you?

[nikic]

LGTM, but a second opinion wouldn't hurt.