SPV_KHR_poison_freeze

SPV_KHR_poison_freeze

To report problems with this extension, please open a new issue at:

https://github.com/KhronosGroup/SPIRV-Registry

Copyright (c) 2025-2026 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html

Experimental

This extension is written against the SPIR-V Specification, Version 1.6 Revision 7.

This extension requires SPIR-V 1.0.

This extension adds the OpFreezeKHR instructions that enables compilers targeting SPIR-V to force a poison value to take an unspecified but stable value, while leaving existing stable values alone. In addition, a new execution mode is added that modifies several existing operations to now produce poison rather than directly resulting in undefined behavior.

There has been a long standing clarity issue around the handling of undefined values in SPIR-V; some developers have assumed "undefined values" to imply that a single stable value is returned, while others took the meaning of OpUndef and assumed this applied. In practice, the edges of this have never been tested in any client APIs, so the details remained fuzzy until the core specification was updated to define the concept of poison, bringing it in line with LLVM’s solution to this problem.

However, just defining poison acknowledges that a suite of things that people have expected to work actually don’t work - and there is no clear fallback. This makes generating sound SPIR-V that avoids undefined behavior challenging, which is a particular problem for languages like WGSL where avoiding undefined behavior is critically important.

One solution to this problem could have been to just start testing if implementations are returning stable values or undefined values already. Unfortunately, without testing the likelihood is that many existing implementations would retroactively be considered buggy. Any implementations that updated to the newer definition would also likely have a negative performance impact on execution existing code, even if that code did not need such strong guarantees. It also means that client APIs and implementations would expend a lot of effort testing and fixing compilers to do something that we don’t necessarily want for the long term anyway, which brings us to the other option.

Looking to LLVM, they solved this issue by introducing the "freeze" instruction. This instruction can be used to turn a poison or undef value into a static valid value, with the expectation that higher level language compilers can use this instruction to make tighter guarantees about handling of undefined values. SPIR-V defining a similar instruction with a 1:1 meaning would also give a clean and straightforward translation between LLVM IR and SPIR-V, which is important in an ecosystem where translation both ways is relied upon by a huge number of tools and implementations.

This document thus proposes introducing a freeze instruction, as well as changing some instances of undefined behavior into generating poison.

To use this extension within a SPIR-V module, the following OpExtension must be present in the module: