llvm.org GIT mirror llvm / 2528c30
[LangRef] Clarify poison semantics I find the current documentation of poison somewhat confusing, mainly because its use of "undefined behavior" doesn't seem to align with our usual interpretation (of immediate UB). Especially the sentence "any instruction that has a dependence on a poison value has undefined behavior" is very confusing. Clarify poison semantics by: * Replacing the introductory paragraph with the standard rationale for having poison values. * Spelling out that instructions depending on poison return poison. * Spelling out how we go from a poison value to immediate undefined behavior and give the two examples we currently use in ValueTracking. * Spelling out that side effects depending on poison are UB. Differential Revision: https://reviews.llvm.org/D63044 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@363320 91177308-0d34-0410-b5e6-96231b3b80d8 Nikita Popov a month ago
2 changed file(s) with 25 addition(s) and 10 deletion(s). Raw diff Collapse all Expand all
21522152 address range of the allocated storage.
21532153 - A null pointer in the default address-space is associated with no
21542154 address.
2155 - An :ref:`undef value ` in *any* address-space is
2156 associated with no address.
21552157 - An integer constant other than zero or a pointer value returned from
21562158 a function not defined within LLVM may be associated with address
21572159 ranges allocated through mechanisms other than those provided by
32043206 Poison Values
32053207 -------------
32063208
3207 Poison values are similar to :ref:`undef values `, however
3208 they also represent the fact that an instruction or constant expression
3209 that cannot evoke side effects has nevertheless detected a condition
3210 that results in undefined behavior.
3209 In order to facilitate speculative execution, many instructions do not
3210 invoke immediate undefined behavior when provided with illegal operands,
3211 and return a poison value instead.
32113212
32123213 There is currently no way of representing a poison value in the IR; they
32133214 only exist when produced by operations such as :ref:`add ` with
32443245 successor.
32453246 - Dependence is transitive.
32463247
3247 Poison values have the same behavior as :ref:`undef values `,
3248 with the additional effect that any instruction that has a *dependence*
3249 on a poison value has undefined behavior.
3248 An instruction that *depends* on a poison value, produces a poison value
3249 itself. A poison value may be relaxed into an
3250 :ref:`undef value `, which takes an arbitrary bit-pattern.
3251
3252 This means that immediate undefined behavior occurs if a poison value is
3253 used as an instruction operand that has any values that trigger undefined
3254 behavior. Notably this includes (but is not limited to):
3255
3256 - The pointer operand of a :ref:`load `, :ref:`store ` or
3257 any other pointer dereferencing instruction (independent of address
3258 space).
3259 - The divisor operand of a ``udiv``, ``sdiv``, ``urem`` or ``srem``
3260 instruction.
3261
3262 Additionally, undefined behavior occurs if a side effect *depends* on poison.
3263 This includes side effects that are control dependent on a poisoned branch.
32503264
32513265 Here are some examples:
32523266
32563270 %poison = sub nuw i32 0, 1 ; Results in a poison value.
32573271 %still_poison = and i32 %poison, 0 ; 0, but also poison.
32583272 %poison_yet_again = getelementptr i32, i32* @h, i32 %still_poison
3259 store i32 0, i32* %poison_yet_again ; memory at @h[0] is poisoned
3273 store i32 0, i32* %poison_yet_again ; Undefined behavior due to
3274 ; store to poison.
32603275
32613276 store i32 %poison, i32* @g ; Poison value stored to memory.
32623277 %poison2 = load i32, i32* @g ; Poison value loaded back from memory.
3263
3264 store volatile i32 %poison, i32* @g ; External observation; undefined behavior.
32653278
32663279 %narrowaddr = bitcast i32* @g to i16*
32673280 %wideaddr = bitcast i32* @g to i64*
43354335 }
43364336
43374337 bool llvm::propagatesFullPoison(const Instruction *I) {
4338 // TODO: This should include all instructions apart from phis, selects and
4339 // call-like instructions.
43384340 switch (I->getOpcode()) {
43394341 case Instruction::Add:
43404342 case Instruction::Sub: