SPIR-V Dialect

This document describes the design of the SPIR-V dialect in MLIR. It lists various design choices we made for modeling different SPIR-V mechanisms, and their rationale.

This document also explains in a high-level manner how different components are organized and implemented in the code and gives steps to follow for extending them.

This document assumes familiarity with SPIR-V. SPIR-V is the Khronos Group’s binary intermediate language for representing graphics shaders and compute kernels. It is adopted by multiple Khronos Group’s APIs, including Vulkan and OpenCL. It is fully defined in a human-readable specification; the syntax of various SPIR-V instructions are encoded in a machine-readable grammar.

Design Guidelines ¶

SPIR-V is a binary intermediate language that serves dual purpose: on one side, it is an intermediate language to represent graphics shaders and compute kernels for high-level languages to target; on the other side, it defines a stable binary format for hardware driver consumption. As a result, SPIR-V has design principles pertain to not only intermediate language, but also binary format. For example, regularity is one of the design goals of SPIR-V. All concepts are represented as SPIR-V instructions, including declaring extensions and capabilities, defining types and constants, defining functions, attaching additional properties to computation results, etc. This way favors binary encoding and decoding for driver consumption but not necessarily compiler transformations.

Dialect design principles ¶

The main objective of the SPIR-V dialect is to be a proper intermediate representation (IR) to facilitate compiler transformations. While we still aim to support serializing to and deserializing from the binary format for various good reasons, the binary format and its concerns play less a role in the design of the SPIR-V dialect: when there is a trade-off to be made between favoring IR and supporting binary format, we lean towards the former.

On the IR aspect, the SPIR-V dialect aims to model SPIR-V at the same semantic level. It is not intended to be a higher level or lower level abstraction than the SPIR-V specification. Those abstractions are easily outside the domain of SPIR-V and should be modeled with other proper dialects so they can be shared among various compilation paths. Because of the dual purpose of SPIR-V, SPIR-V dialect staying at the same semantic level as the SPIR-V specification also means we can still have straightforward serialization and deserialization for the majority of functionalities.

To summarize, the SPIR-V dialect follows the following design principles:

• Stay as the same semantic level as the SPIR-V specification by having one-to-one mapping for most concepts and entities.
• Adopt SPIR-V specification’s syntax if possible, but deviate intentionally to utilize MLIR mechanisms if it results in better representation and benefits transformation.
• Be straightforward to serialize into and deserialize from the SPIR-V binary format.

SPIR-V is designed to be consumed by hardware drivers, so its representation is quite clear, yet verbose for some cases. Allowing representational deviation gives us the flexibility to reduce the verbosity by using MLIR mechanisms.

Dialect scopes ¶

SPIR-V supports multiple execution environments, specified by client APIs. Notable adopters include Vulkan and OpenCL. It follows that the SPIR-V dialect should support multiple execution environments if to be a proper proxy of SPIR-V in MLIR systems. The SPIR-V dialect is designed with these considerations: it has proper support for versions, extensions, and capabilities and is as extensible as SPIR-V specification.

Conventions ¶

The SPIR-V dialect adopts the following conventions for IR:

• The prefix for all SPIR-V types and operations are spirv..
• All instructions in an extended instruction set are further qualified with the extended instruction set’s prefix. For example, all operations in the GLSL extended instruction set have the prefix of spirv.GL..
• Ops that directly mirror instructions in the specification have CamelCase names that are the same as the instruction opnames (without the Op prefix). For example, spirv.FMul is a direct mirror of OpFMul in the specification. Such an op will be serialized into and deserialized from one SPIR-V instruction.
• Ops with snake_case names are those that have different representation from corresponding instructions (or concepts) in the specification. These ops are mostly for defining the SPIR-V structure. For example, spirv.module and spirv.Constant. They may correspond to one or more instructions during (de)serialization.
• Ops with mlir.snake_case names are those that have no corresponding instructions (or concepts) in the binary format. They are introduced to satisfy MLIR structural requirements. For example, spirv.mlir.merge. They map to no instructions during (de)serialization.

(TODO: consider merging the last two cases and adopting spirv.mlir. prefix for them.)

Module ¶

A SPIR-V module is defined via the spirv.module op, which has one region that contains one block. Model-level instructions, including function definitions, are all placed inside the block. Functions are defined using the builtin func op.

We choose to model a SPIR-V module with a dedicated spirv.module op based on the following considerations:

• It maps cleanly to a SPIR-V module in the specification.
• We can enforce SPIR-V specific verification that is suitable to be performed at the module-level.
• We can attach additional model-level attributes.
• We can control custom assembly form.

The spirv.module op’s region cannot capture SSA values from outside, neither implicitly nor explicitly. The spirv.module op’s region is closed as to what ops can appear inside: apart from the builtin func op, it can only contain ops from the SPIR-V dialect. The spirv.module op’s verifier enforces this rule. This meaningfully guarantees that a spirv.module can be the entry point and boundary for serialization.

Module-level operations ¶

SPIR-V binary format defines the following sections:

1. Capabilities required by the module.
2. Extensions required by the module.
3. Extended instructions sets required by the module.
4. Addressing and memory model specification.
5. Entry point specifications.
6. Execution mode declarations.
7. Debug instructions.
8. Annotation/decoration instructions.
9. Type, constant, global variables.
10. Function declarations.
11. Function definitions.

Basically, a SPIR-V binary module contains multiple module-level instructions followed by a list of functions. Those module-level instructions are essential and they can generate result ids referenced by functions, notably, declaring resource variables to interact with the execution environment.

Compared to the binary format, we adjust how these module-level SPIR-V instructions are represented in the SPIR-V dialect:

Use MLIR attributes for metadata ¶

• Requirements for capabilities, extensions, extended instruction sets, addressing model, and memory model are conveyed using spirv.module attributes. This is considered better because these information are for the execution environment. It’s easier to probe them if on the module op itself.
• Annotations/decoration instructions are “folded” into the instructions they decorate and represented as attributes on those ops. This eliminates potential forward references of SSA values, improves IR readability, and makes querying the annotations more direct. More discussions can be found in the Decorations section.

Model types with MLIR custom types ¶

• Types are represented using MLIR builtin types and SPIR-V dialect specific types. There are no type declaration ops in the SPIR-V dialect. More discussions can be found in the Types section later.

Unify and localize constants ¶

• Various normal constant instructions are represented by the same spirv.Constant op. Those instructions are just for constants of different types; using one op to represent them reduces IR verbosity and makes transformations less tedious.
• Normal constants are not placed in spirv.module’s region; they are localized into functions. This is to make functions in the SPIR-V dialect to be isolated and explicit capturing. Constants are cheap to duplicate given attributes are made unique in MLIRContext.

Adopt symbol-based global variables and specialization constant ¶

• Global variables are defined with the spirv.GlobalVariable op. They do not generate SSA values. Instead they have symbols and should be referenced via symbols. To use global variables in a function block, spirv.mlir.addressof is needed to turn the symbol into an SSA value.
• Specialization constants are defined with the spirv.SpecConstant op. Similar to global variables, they do not generate SSA values and have symbols for reference, too. spirv.mlir.referenceof is needed to turn the symbol into an SSA value for use in a function block.

The above choices enables functions in the SPIR-V dialect to be isolated and explicit capturing.

Disallow implicit capturing in functions ¶

• In SPIR-V specification, functions support implicit capturing: they can reference SSA values defined in modules. In the SPIR-V dialect functions are defined with func op, which disallows implicit capturing. This is more friendly to compiler analyses and transformations. More discussions can be found in the Function section later.

Model entry points and execution models as normal ops ¶

• A SPIR-V module can have multiple entry points. And these entry points refer to the function and interface variables. It’s not suitable to model them as spirv.module op attributes. We can model them as normal ops of using symbol references.
• Similarly for execution modes, which are coupled with entry points, we can model them as normal ops in spirv.module’s region.

Decorations ¶

Annotations/decorations provide additional information on result ids. In SPIR-V, all instructions can generate result ids, including value-computing and type-defining ones.

For decorations on value result ids, we can just have a corresponding attribute attached to the operation generating the SSA value. For example, for the following SPIR-V:

OpDecorate %v1 RelaxedPrecision
OpDecorate %v2 NoContraction
...
%v1 = OpFMul %float %0 %0
%v2 = OpFMul %float %1 %1

We can represent them in the SPIR-V dialect as:

%v1 = "spirv.FMul"(%0, %0) {RelaxedPrecision: unit} : (f32, f32) -> (f32)
%v2 = "spirv.FMul"(%1, %1) {NoContraction: unit} : (f32, f32) -> (f32)

This approach benefits transformations. Essentially those decorations are just additional properties of the result ids (and thus their defining instructions). In SPIR-V binary format, they are just represented as instructions. Literally following SPIR-V binary format means we need to through def-use chains to find the decoration instructions and query information from them.

For decorations on type result ids, notice that practically, only result ids generated from composite types (e.g., OpTypeArray, OpTypeStruct) need to be decorated for memory layouting purpose (e.g., ArrayStride, Offset, etc.); scalar/vector types are required to be uniqued in SPIR-V. Therefore, we can just encode them directly in the dialect-specific type.

Types ¶

Theoretically we can define all SPIR-V types using MLIR extensible type system, but other than representational purity, it does not buy us more. Instead, we need to maintain the code and invest in pretty printing them. So we prefer to use builtin types if possible.

The SPIR-V dialect reuses builtin integer, float, and vector types:

For integer types, the SPIR-V dialect supports all signedness semantics (signless, signed, unsigned) in order to ease transformations from higher level dialects. However, SPIR-V spec only defines two signedness semantics state: 0 indicates unsigned, or no signedness semantics, 1 indicates signed semantics. So both iN and uiN are serialized into the same OpTypeInt N 0. For deserialization, we always treat OpTypeInt N 0 as iN.

mlir::NoneType is used for SPIR-V OpTypeVoid; builtin function types are used for SPIR-V OpTypeFunction types.

The SPIR-V dialect and defines the following dialect-specific types:

spirv-type ::= array-type
             | image-type
             | pointer-type
             | runtime-array-type
             | sampled-image-type
             | struct-type

Array type ¶

This corresponds to SPIR-V array type. Its syntax is

element-type ::= integer-type
               | floating-point-type
               | vector-type
               | spirv-type

array-type ::= `!spirv.array` `<` integer-literal `x` element-type
               (`,` `stride` `=` integer-literal)? `>`

For example,

!spirv.array<4 x i32>
!spirv.array<4 x i32, stride = 4>
!spirv.array<16 x vector<4 x f32>>

Image type ¶

This corresponds to SPIR-V image type. Its syntax is

dim ::= `1D` | `2D` | `3D` | `Cube` | <and other SPIR-V Dim specifiers...>

depth-info ::= `NoDepth` | `IsDepth` | `DepthUnknown`

arrayed-info ::= `NonArrayed` | `Arrayed`

sampling-info ::= `SingleSampled` | `MultiSampled`

sampler-use-info ::= `SamplerUnknown` | `NeedSampler` | `NoSampler`

format ::= `Unknown` | `Rgba32f` | <and other SPIR-V Image Formats...>

image-type ::= `!spirv.image<` element-type `,` dim `,` depth-info `,`
                           arrayed-info `,` sampling-info `,`
                           sampler-use-info `,` format `>`

For example,

!spirv.image<f32, 1D, NoDepth, NonArrayed, SingleSampled, SamplerUnknown, Unknown>
!spirv.image<f32, Cube, IsDepth, Arrayed, MultiSampled, NeedSampler, Rgba32f>

Pointer type ¶

This corresponds to SPIR-V pointer type. Its syntax is

storage-class ::= `UniformConstant`
                | `Uniform`
                | `Workgroup`
                | <and other storage classes...>

pointer-type ::= `!spirv.ptr<` element-type `,` storage-class `>`

For example,

!spirv.ptr<i32, Function>
!spirv.ptr<vector<4 x f32>, Uniform>

Runtime array type ¶

This corresponds to SPIR-V runtime array type. Its syntax is

runtime-array-type ::= `!spirv.rtarray` `<` element-type (`,` `stride` `=` integer-literal)? `>`

For example,

!spirv.rtarray<i32>
!spirv.rtarray<i32, stride=4>
!spirv.rtarray<vector<4 x f32>>

Sampled image type ¶

This corresponds to SPIR-V sampled image type. Its syntax is

sampled-image-type ::= `!spirv.sampled_image<!spirv.image<` element-type `,` dim `,` depth-info `,`
                                                        arrayed-info `,` sampling-info `,`
                                                        sampler-use-info `,` format `>>`

For example,

!spirv.sampled_image<!spirv.image<f32, Dim1D, NoDepth, NonArrayed, SingleSampled, NoSampler, Unknown>>
!spirv.sampled_image<!spirv.image<i32, Rect, DepthUnknown, Arrayed, MultiSampled, NeedSampler, R8ui>>

Struct type ¶

This corresponds to SPIR-V struct type. Its syntax is

struct-member-decoration ::= integer-literal? spirv-decoration*
struct-type ::= `!spirv.struct<` spirv-type (`[` struct-member-decoration `]`)?
                     (`, ` spirv-type (`[` struct-member-decoration `]`)? `>`

For Example,

!spirv.struct<f32>
!spirv.struct<f32 [0]>
!spirv.struct<f32, !spirv.image<f32, 1D, NoDepth, NonArrayed, SingleSampled, SamplerUnknown, Unknown>>
!spirv.struct<f32 [0], i32 [4]>

Function ¶

In SPIR-V, a function construct consists of multiple instructions involving OpFunction, OpFunctionParameter, OpLabel, OpFunctionEnd.

// int f(int v) { return v; }
%1 = OpTypeInt 32 0
%2 = OpTypeFunction %1 %1
%3 = OpFunction %1 %2
%4 = OpFunctionParameter %1
%5 = OpLabel
%6 = OpReturnValue %4
     OpFunctionEnd

This construct is very clear yet quite verbose. It is intended for driver consumption. There is little benefit to literally replicate this construct in the SPIR-V dialect. Instead, we reuse the builtin func op to express functions more concisely:

func.func @f(%arg: i32) -> i32 {
  "spirv.ReturnValue"(%arg) : (i32) -> (i32)
}

A SPIR-V function can have at most one result. It cannot contain nested functions or non-SPIR-V operations. spirv.module verifies these requirements.

A major difference between the SPIR-V dialect and the SPIR-V specification for functions is that the former are isolated and require explicit capturing, while the latter allows implicit capturing. In SPIR-V specification, functions can refer to SSA values (generated by constants, global variables, etc.) defined in modules. The SPIR-V dialect adjusted how constants and global variables are modeled to enable isolated functions. Isolated functions are more friendly to compiler analyses and transformations. This also enables the SPIR-V dialect to better utilize core infrastructure: many functionalities in the core infrastructure require ops to be isolated, e.g., the greedy pattern rewriter can only act on ops isolated from above.

(TODO: create a dedicated spirv.fn op for SPIR-V functions.)

Operations ¶

In SPIR-V, instruction is a generalized concept; a SPIR-V module is just a sequence of instructions. Declaring types, expressing computations, annotating result ids, expressing control flows and others are all in the form of instructions.

We only discuss instructions expressing computations here, which can be represented via SPIR-V dialect ops. Module-level instructions for declarations and definitions are represented differently in the SPIR-V dialect as explained earlier in the Module-level operations section.

An instruction computes zero or one result from zero or more operands. The result is a new result id. An operand can be a result id generated by a previous instruction, an immediate value, or a case of an enum type. We can model result id operands and results with MLIR SSA values; for immediate value and enum cases, we can model them with MLIR attributes.

For example,

%i32 = OpTypeInt 32 0
%c42 = OpConstant %i32 42
...
%3 = OpVariable %i32 Function 42
%4 = OpIAdd %i32 %c42 %c42

can be represented in the dialect as

%0 = "spirv.Constant"() { value = 42 : i32 } : () -> i32
%1 = "spirv.Variable"(%0) { storage_class = "Function" } : (i32) -> !spirv.ptr<i32, Function>
%2 = "spirv.IAdd"(%0, %0) : (i32, i32) -> i32

Operation documentation is written in each op’s Op Definition Spec using TableGen. A markdown version of the doc can be generated using mlir-tblgen -gen-doc and is attached in the Operation definitions section.

Ops from extended instruction sets ¶

Analogically extended instruction set is a mechanism to import SPIR-V instructions within another namespace. GLSL.std.450 is an extended instruction set that provides common mathematical routines that should be supported. Instead of modeling OpExtInstImport as a separate op and use a single op to model OpExtInst for all extended instructions, we model each SPIR-V instruction in an extended instruction set as a separate op with the proper name prefix. For example, for

%glsl = OpExtInstImport "GLSL.std.450"

%f32 = OpTypeFloat 32
%cst = OpConstant %f32 ...

%1 = OpExtInst %f32 %glsl 28 %cst
%2 = OpExtInst %f32 %glsl 31 %cst

we can have

%1 = "spirv.GL.Log"(%cst) : (f32) -> (f32)
%2 = "spirv.GL.Sqrt"(%cst) : (f32) -> (f32)

Control Flow ¶

SPIR-V binary format uses merge instructions (OpSelectionMerge and OpLoopMerge) to declare structured control flow. They explicitly declare a header block before the control flow diverges and a merge block where control flow subsequently converges. These blocks delimit constructs that must nest, and can only be entered and exited in structured ways.

In the SPIR-V dialect, we use regions to mark the boundary of a structured control flow construct. With this approach, it’s easier to discover all blocks belonging to a structured control flow construct. It is also more idiomatic to MLIR system.

We introduce a spirv.mlir.selection and spirv.mlir.loop op for structured selections and loops, respectively. The merge targets are the next ops following them. Inside their regions, a special terminator, spirv.mlir.merge is introduced for branching to the merge target.

Selection ¶

spirv.mlir.selection defines a selection construct. It contains one region. The region should contain at least two blocks: one selection header block and one merge block.

• The selection header block should be the first block. It should contain the spirv.BranchConditional or spirv.Switch op.
• The merge block should be the last block. The merge block should only contain a spirv.mlir.merge op. Any block can branch to the merge block for early exit.

               +--------------+
               | header block |                 (may have multiple outgoing branches)
               +--------------+
                    / | \
                     ...


   +---------+   +---------+   +---------+
   | case #0 |   | case #1 |   | case #2 |  ... (may have branches between each other)
   +---------+   +---------+   +---------+


                     ...
                    \ | /
                      v
               +-------------+
               | merge block |                  (may have multiple incoming branches)
               +-------------+

For example, for the given function

void loop(bool cond) {
  int x = 0;
  if (cond) {
    x = 1;
  } else {
    x = 2;
  }
  // ...
}

It will be represented as

func.func @selection(%cond: i1) -> () {
  %zero = spirv.Constant 0: i32
  %one = spirv.Constant 1: i32
  %two = spirv.Constant 2: i32
  %x = spirv.Variable init(%zero) : !spirv.ptr<i32, Function>

  spirv.mlir.selection {
    spirv.BranchConditional %cond, ^then, ^else

  ^then:
    spirv.Store "Function" %x, %one : i32
    spirv.Branch ^merge

  ^else:
    spirv.Store "Function" %x, %two : i32
    spirv.Branch ^merge

  ^merge:
    spirv.mlir.merge
  }

  // ...
}

Loop ¶

spirv.mlir.loop defines a loop construct. It contains one region. The region should contain at least four blocks: one entry block, one loop header block, one loop continue block, one merge block.

• The entry block should be the first block and it should jump to the loop header block, which is the second block.
• The merge block should be the last block. The merge block should only contain a spirv.mlir.merge op. Any block except the entry block can branch to the merge block for early exit.
• The continue block should be the second to last block and it should have a branch to the loop header block.
• The loop continue block should be the only block, except the entry block, branching to the loop header block.

    +-------------+
    | entry block |           (one outgoing branch)
    +-------------+
           |
           v
    +-------------+           (two incoming branches)
    | loop header | <-----+   (may have one or two outgoing branches)
    +-------------+       |
                          |
          ...             |
         \ | /            |
           v              |
   +---------------+      |   (may have multiple incoming branches)
   | loop continue | -----+   (may have one or two outgoing branches)
   +---------------+

          ...
         \ | /
           v
    +-------------+           (may have multiple incoming branches)
    | merge block |
    +-------------+

The reason to have another entry block instead of directly using the loop header block as the entry block is to satisfy region’s requirement: entry block of region may not have predecessors. We have a merge block so that branch ops can reference it as successors. The loop continue block here corresponds to “continue construct” using SPIR-V spec’s term; it does not mean the “continue block” as defined in the SPIR-V spec, which is “a block containing a branch to an OpLoopMerge instruction’s Continue Target.”

For example, for the given function

void loop(int count) {
  for (int i = 0; i < count; ++i) {
    // ...
  }
}

It will be represented as

func.func @loop(%count : i32) -> () {
  %zero = spirv.Constant 0: i32
  %one = spirv.Constant 1: i32
  %var = spirv.Variable init(%zero) : !spirv.ptr<i32, Function>

  spirv.mlir.loop {
    spirv.Branch ^header

  ^header:
    %val0 = spirv.Load "Function" %var : i32
    %cmp = spirv.SLessThan %val0, %count : i32
    spirv.BranchConditional %cmp, ^body, ^merge

  ^body:
    // ...
    spirv.Branch ^continue

  ^continue:
    %val1 = spirv.Load "Function" %var : i32
    %add = spirv.IAdd %val1, %one : i32
    spirv.Store "Function" %var, %add : i32
    spirv.Branch ^header

  ^merge:
    spirv.mlir.merge
  }
  return
}

Block argument for Phi ¶

There are no direct Phi operations in the SPIR-V dialect; SPIR-V OpPhi instructions are modelled as block arguments in the SPIR-V dialect. (See the Rationale doc for “Block Arguments vs Phi nodes”.) Each block argument corresponds to one OpPhi instruction in the SPIR-V binary format. For example, for the following SPIR-V function foo:

  %foo = OpFunction %void None ...
%entry = OpLabel
  %var = OpVariable %_ptr_Function_int Function
         OpSelectionMerge %merge None
         OpBranchConditional %true %true %false
 %true = OpLabel
         OpBranch %phi
%false = OpLabel
         OpBranch %phi
  %phi = OpLabel
  %val = OpPhi %int %int_1 %false %int_0 %true
         OpStore %var %val
         OpReturn
%merge = OpLabel
         OpReturn
         OpFunctionEnd

It will be represented as:

func.func @foo() -> () {
  %var = spirv.Variable : !spirv.ptr<i32, Function>

  spirv.mlir.selection {
    %true = spirv.Constant true
    spirv.BranchConditional %true, ^true, ^false

  ^true:
    %zero = spirv.Constant 0 : i32
    spirv.Branch ^phi(%zero: i32)

  ^false:
    %one = spirv.Constant 1 : i32
    spirv.Branch ^phi(%one: i32)

  ^phi(%arg: i32):
    spirv.Store "Function" %var, %arg : i32
    spirv.Return

  ^merge:
    spirv.mlir.merge
  }
  spirv.Return
}

Version, extensions, capabilities ¶

SPIR-V supports versions, extensions, and capabilities as ways to indicate the availability of various features (types, ops, enum cases) on target hardware. For example, non-uniform group operations were missing before v1.3, and they require special capabilities like GroupNonUniformArithmetic to be used. These availability information relates to target environment and affects the legality of patterns during dialect conversion.

SPIR-V ops’ availability requirements are modeled with op interfaces:

• QueryMinVersionInterface and QueryMaxVersionInterface for version requirements
• QueryExtensionInterface for extension requirements
• QueryCapabilityInterface for capability requirements

These interface declarations are auto-generated from TableGen definitions included in SPIRVBase.td. At the moment all SPIR-V ops implement the above interfaces.

SPIR-V ops’ availability implementation methods are automatically synthesized from the availability specification on each op and enum attribute in TableGen. An op needs to look into not only the opcode but also operands to derive its availability requirements. For example, spirv.ControlBarrier requires no special capability if the execution scope is Subgroup, but it will require the VulkanMemoryModel capability if the scope is QueueFamily.

SPIR-V types’ availability implementation methods are manually written as overrides in the SPIR-V type hierarchy.

These availability requirements serve as the “ingredients” for the SPIRVConversionTarget and SPIRVTypeConverter to perform op and type conversions, by following the requirements in target environment.

Target environment ¶

SPIR-V aims to support multiple execution environments as specified by client APIs. These execution environments affect the availability of certain SPIR-V features. For example, a Vulkan 1.1 implementation must support the 1.0, 1.1, 1.2, and 1.3 versions of SPIR-V and the 1.0 version of the SPIR-V extended instructions for GLSL. Further Vulkan extensions may enable more SPIR-V instructions.

SPIR-V compilation should also take into consideration of the execution environment, so we generate SPIR-V modules valid for the target environment. This is conveyed by the spirv.target_env (spirv::TargetEnvAttr) attribute. It should be of #spirv.target_env attribute kind, which is defined as:

spirv-version    ::= `v1.0` | `v1.1` | ...
spirv-extension  ::= `SPV_KHR_16bit_storage` | `SPV_EXT_physical_storage_buffer` | ...
spirv-capability ::= `Shader` | `Kernel` | `GroupNonUniform` | ...

spirv-extension-list     ::= `[` (spirv-extension-elements)? `]`
spirv-extension-elements ::= spirv-extension (`,` spirv-extension)*

spirv-capability-list     ::= `[` (spirv-capability-elements)? `]`
spirv-capability-elements ::= spirv-capability (`,` spirv-capability)*

spirv-resource-limits ::= dictionary-attribute

spirv-vce-attribute ::= `#` `spirv.vce` `<`
                            spirv-version `,`
                            spirv-capability-list `,`
                            spirv-extensions-list `>`

spirv-vendor-id ::= `AMD` | `NVIDIA` | ...
spirv-device-type ::= `DiscreteGPU` | `IntegratedGPU` | `CPU` | ...
spirv-device-id ::= integer-literal
spirv-device-info ::= spirv-vendor-id (`:` spirv-device-type (`:` spirv-device-id)?)?

spirv-target-env-attribute ::= `#` `spirv.target_env` `<`
                                  spirv-vce-attribute,
                                  (spirv-device-info `,`)?
                                  spirv-resource-limits `>`

The attribute has a few fields:

• A #spirv.vce (spirv::VerCapExtAttr) attribute:
  • The target SPIR-V version.
  • A list of SPIR-V extensions for the target.
  • A list of SPIR-V capabilities for the target.
• A dictionary of target resource limits (see the Vulkan spec for explanation):
  • max_compute_workgroup_invocations
  • max_compute_workgroup_size

For example,

module attributes {
spirv.target_env = #spirv.target_env<
    #spirv.vce<v1.3, [Shader, GroupNonUniform], [SPV_KHR_8bit_storage]>,
    ARM:IntegratedGPU,
    {
      max_compute_workgroup_invocations = 128 : i32,
      max_compute_workgroup_size = dense<[128, 128, 64]> : vector<3xi32>
    }>
} { ... }

Dialect conversion framework will utilize the information in spirv.target_env to properly filter out patterns and ops not available in the target execution environment. When targeting SPIR-V, one needs to create a SPIRVConversionTarget by providing such an attribute.

Shader interface (ABI) ¶

SPIR-V itself is just expressing computation happening on GPU device. SPIR-V programs themselves are not enough for running workloads on GPU; a companion host application is needed to manage the resources referenced by SPIR-V programs and dispatch the workload. For the Vulkan execution environment, the host application will be written using Vulkan API. Unlike CUDA, the SPIR-V program and the Vulkan application are typically authored with different front-end languages, which isolates these two worlds. Yet they still need to match interfaces: the variables declared in a SPIR-V program for referencing resources need to match with the actual resources managed by the application regarding their parameters.

Still using Vulkan as an example execution environment, there are two primary resource types in Vulkan: buffers and images. They are used to back various uses that may differ regarding the classes of operations (load, store, atomic) to be performed. These uses are differentiated via descriptor types. (For example, uniform storage buffer descriptors can only support load operations while storage buffer descriptors can support load, store, and atomic operations.) Vulkan uses a binding model for resources. Resources are associated with descriptors and descriptors are further grouped into sets. Each descriptor thus has a set number and a binding number. Descriptors in the application corresponds to variables in the SPIR-V program. Their parameters must match, including but not limited to set and binding numbers.

Apart from buffers and images, there is other data that is set up by Vulkan and referenced inside the SPIR-V program, for example, push constants. They also have parameters that require matching between the two worlds.

The interface requirements are external information to the SPIR-V compilation path in MLIR. Besides, each Vulkan application may want to handle resources differently. To avoid duplication and to share common utilities, a SPIR-V shader interface specification needs to be defined to provide the external requirements to and guide the SPIR-V compilation path.

Shader interface attributes ¶

The SPIR-V dialect defines a few attributes for specifying these interfaces:

• spirv.entry_point_abi is a struct attribute that should be attached to the entry function. It contains:
  • local_size for specifying the local work group size for the dispatch.
• spirv.interface_var_abi is attribute that should be attached to each operand and result of the entry function. It should be of #spirv.interface_var_abi attribute kind, which is defined as:

spv-storage-class     ::= `StorageBuffer` | ...
spv-descriptor-set    ::= integer-literal
spv-binding           ::= integer-literal
spv-interface-var-abi ::= `#` `spirv.interface_var_abi` `<(` spv-descriptor-set
                          `,` spv-binding `)` (`,` spv-storage-class)? `>`

For example,

#spirv.interface_var_abi<(0, 0), StorageBuffer>
#spirv.interface_var_abi<(0, 1)>

The attribute has a few fields:

• Descriptor set number for the corresponding resource variable.
• Binding number for the corresponding resource variable.
• Storage class for the corresponding resource variable.

The SPIR-V dialect provides a LowerABIAttributesPass that uses this information to lower the entry point function and its ABI consistent with the Vulkan validation rules. Specifically,

• Creates spirv.GlobalVariables for the arguments, and replaces all uses of the argument with this variable. The SSA value used for replacement is obtained using the spirv.mlir.addressof operation.
• Adds the spirv.EntryPoint and spirv.ExecutionMode operations into the spirv.module for the entry function.

Serialization and deserialization ¶

Although the main objective of the SPIR-V dialect is to act as a proper IR for compiler transformations, being able to serialize to and deserialize from the binary format is still very valuable for many good reasons. Serialization enables the artifacts of SPIR-V compilation to be consumed by an execution environment; deserialization allows us to import SPIR-V binary modules and run transformations on them. So serialization and deserialization are supported from the very beginning of the development of the SPIR-V dialect.

The serialization library provides two entry points, mlir::spirv::serialize() and mlir::spirv::deserialize(), for converting a MLIR SPIR-V module to binary format and back. The Code organization explains more about this.

Given that the focus is transformations, which inevitably means changes to the binary module; so serialization is not designed to be a general tool for investigating the SPIR-V binary module and does not guarantee roundtrip equivalence (at least for now). For the latter, please use the assembler/disassembler in the SPIRV-Tools project.

A few transformations are performed in the process of serialization because of the representational differences between SPIR-V dialect and binary format:

• Attributes on spirv.module are emitted as their corresponding SPIR-V instructions.
• Types are serialized into OpType* instructions in the SPIR-V binary module section for types, constants, and global variables.
• spirv.Constants are unified and placed in the SPIR-V binary module section for types, constants, and global variables.
• Attributes on ops, if not part of the op’s binary encoding, are emitted as OpDecorate* instructions in the SPIR-V binary module section for decorations.
• spirv.mlir.selections and spirv.mlir.loops are emitted as basic blocks with Op*Merge instructions in the header block as required by the binary format.
• Block arguments are materialized as OpPhi instructions at the beginning of the corresponding blocks.

Similarly, a few transformations are performed during deserialization:

• Instructions for execution environment requirements (extensions, capabilities, extended instruction sets, etc.) will be placed as attributes on spirv.module.
• OpType* instructions will be converted into proper mlir::Types.
• OpConstant* instructions are materialized as spirv.Constant at each use site.
• OpVariable instructions will be converted to spirv.GlobalVariable ops if in module-level; otherwise they will be converted into spirv.Variable ops.
• Every use of a module-level OpVariable instruction will materialize a spirv.mlir.addressof op to turn the symbol of the corresponding spirv.GlobalVariable into an SSA value.
• Every use of a OpSpecConstant instruction will materialize a spirv.mlir.referenceof op to turn the symbol of the corresponding spirv.SpecConstant into an SSA value.
• OpPhi instructions are converted to block arguments.
• Structured control flow are placed inside spirv.mlir.selection and spirv.mlir.loop.

Conversions ¶

One of the main features of MLIR is the ability to progressively lower from dialects that capture programmer abstraction into dialects that are closer to a machine representation, like SPIR-V dialect. This progressive lowering through multiple dialects is enabled through the use of the DialectConversion framework in MLIR. To simplify targeting SPIR-V dialect using the Dialect Conversion framework, two utility classes are provided.

(Note : While SPIR-V has some validation rules, additional rules are imposed by Vulkan execution environment. The lowering described below implements both these requirements.)

SPIRVConversionTarget ¶

The mlir::spirv::SPIRVConversionTarget class derives from the mlir::ConversionTarget class and serves as a utility to define a conversion target satisfying a given spirv.target_env. It registers proper hooks to check the dynamic legality of SPIR-V ops. Users can further register other legality constraints into the returned SPIRVConversionTarget.

spirv::lookupTargetEnvOrDefault() is a handy utility function to query an spirv.target_env attached in the input IR or use the default to construct a SPIRVConversionTarget.

SPIRVTypeConverter ¶

The mlir::SPIRVTypeConverter derives from mlir::TypeConverter and provides type conversion for builtin types to SPIR-V types conforming to the target environment it is constructed with. If the required extension/capability for the resultant type is not available in the given target environment, convertType() will return a null type.

Builtin scalar types are converted to their corresponding SPIR-V scalar types.

(TODO: Note that if the bitwidth is not available in the target environment, it will be unconditionally converted to 32-bit. This should be switched to properly emulating non-32-bit scalar types.)

Builtin index type need special handling since they are not directly supported in SPIR-V. Currently the index type is converted to i32.

(TODO: Allow for configuring the integer width to use for index types in the SPIR-V dialect)

SPIR-V only supports vectors of 2/3/4 elements; so builtin vector types of these lengths can be converted directly.

(TODO: Convert other vectors of lengths to scalars or arrays)

Builtin memref types with static shape and stride are converted to spirv.ptr<spirv.struct<spirv.array<...>>>s. The resultant SPIR-V array types have the same element type as the source memref and its number of elements is obtained from the layout specification of the memref. The storage class of the pointer type are derived from the memref’s memory space with SPIRVTypeConverter::getStorageClassForMemorySpace().

Utility functions for lowering ¶

Setting layout for shader interface variables ¶

SPIR-V validation rules for shaders require composite objects to be explicitly laid out. If a spirv.GlobalVariable is not explicitly laid out, the utility method mlir::spirv::decorateType implements a layout consistent with the Vulkan shader requirements.

Creating builtin variables ¶

In SPIR-V dialect, builtins are represented using spirv.GlobalVariables, with spirv.mlir.addressof used to get a handle to the builtin as an SSA value. The method mlir::spirv::getBuiltinVariableValue creates a spirv.GlobalVariable for the builtin in the current spirv.module if it does not exist already, and returns an SSA value generated from an spirv.mlir.addressof operation.

Current conversions to SPIR-V ¶

Using the above infrastructure, conversions are implemented from

• [Arith Dialect][MlirArithDialect]
• GPU Dialect : A gpu.module is converted to a spirv.module. A gpu.function within this module is lowered as an entry function.

Code organization ¶

We aim to provide multiple libraries with clear dependencies for SPIR-V related functionalities in MLIR so developers can just choose the needed components without pulling in the whole world.

The dialect ¶

The code for the SPIR-V dialect resides in a few places:

• Public headers are placed in include/mlir/Dialect/SPIRV.
• Libraries are placed in lib/Dialect/SPIRV.
• IR tests are placed in test/Dialect/SPIRV.
• Unit tests are placed in unittests/Dialect/SPIRV.

The whole SPIR-V dialect is exposed via multiple headers for better organization:

• SPIRVDialect.h defines the SPIR-V dialect.
• SPIRVTypes.h defines all SPIR-V specific types.
• SPIRVOps.h defines all SPIR-V operations.
• Serialization.h defines the entry points for serialization and deserialization.

The dialect itself, including all types and ops, is in the MLIRSPIRV library. Serialization functionalities are in the MLIRSPIRVSerialization library.

Op definitions ¶

We use Op Definition Spec to define all SPIR-V ops. They are written in TableGen syntax and placed in various *Ops.td files in the header directory. Those *Ops.td files are organized according to the instruction categories used in the SPIR-V specification, for example, an op belonging to the “Atomics Instructions” section is put in the SPIRVAtomicOps.td file.

SPIRVOps.td serves as the main op definition file that includes all files for specific categories.

SPIRVBase.td defines common classes and utilities used by various op definitions. It contains the TableGen SPIR-V dialect definition, SPIR-V versions, known extensions, various SPIR-V enums, TableGen SPIR-V types, and base op classes, etc.

Many of the contents in SPIRVBase.td, e.g., the opcodes and various enums, and all *Ops.td files can be automatically updated via a Python script, which queries the SPIR-V specification and grammar. This greatly reduces the burden of supporting new ops and keeping updated with the SPIR-V spec. More details on this automated development can be found in the Automated development flow section.

Dialect conversions ¶

The code for conversions from other dialects to the SPIR-V dialect also resides in a few places:

• From GPU dialect: headers are at include/mlir/Conversion/GPUTOSPIRV; libraries are at lib/Conversion/GPUToSPIRV.
• From Func dialect: headers are at include/mlir/Conversion/FuncToSPIRV; libraries are at lib/Conversion/FuncToSPIRV.

These dialect to dialect conversions have their dedicated libraries, MLIRGPUToSPIRV and MLIRFuncToSPIRV, respectively.

There are also common utilities when targeting SPIR-V from any dialect:

• include/mlir/Dialect/SPIRV/Transforms/SPIRVConversion.h contains type converters and other utility functions.
• include/mlir/Dialect/SPIRV/Transforms/Passes.h contains SPIR-V specific analyses and transformations.

These common utilities are implemented in the MLIRSPIRVConversion and MLIRSPIRVTransforms library, respectively.

Rationale ¶

Lowering memrefs to !spirv.array<..> and !spirv.rtarray<..>. ¶

The LLVM dialect lowers memref types to a MemrefDescriptor:

struct MemrefDescriptor {
  void *allocated_ptr; // Pointer to the base allocation.
  void *aligned_ptr;   // Pointer within base allocation which is aligned to
                       // the value set in the memref.
  size_t offset;       // Offset from aligned_ptr from where to get values
                       // corresponding to the memref.
  size_t shape[rank];  // Shape of the memref.
  size_t stride[rank]; // Strides used while accessing elements of the memref.
};

In SPIR-V dialect, we chose not to use a MemrefDescriptor. Instead a memref is lowered directly to a !spirv.ptr<!spirv.array<nelts x elem_type>> when the memref is statically shaped, and !spirv.ptr<!spirv.rtarray<elem_type>> when the memref is dynamically shaped. The rationale behind this choice is described below.

1. Inputs/output buffers to a SPIR-V kernel are specified using OpVariable inside interface storage classes (e.g., Uniform, StorageBuffer, etc.), while kernel private variables reside in non-interface storage classes (e.g., Function, Workgroup, etc.). By default, Vulkan-flavored SPIR-V requires logical addressing mode: one cannot load/store pointers from/to variables and cannot perform pointer arithmetic. Expressing a struct like MemrefDescriptor in interface storage class requires special addressing mode ( PhysicalStorageBuffer) and manipulating such a struct in non-interface storage classes requires special capabilities ( VariablePointers). Requiring these two extensions together will significantly limit the Vulkan-capable device we can target; basically ruling out mobile support..

2. An alternative to having one level of indirection (as is the case with MemrefDescriptors), is to embed the !spirv.array or !spirv.rtarray directly in the MemrefDescriptor, Having such a descriptor at the ABI boundary implies that the first few bytes of the input/output buffers would need to be reserved for shape/stride information. This adds an unnecessary burden on the host side.

3. A more performant approach would be to have the data be an OpVariable, with the shape and strides passed using a separate OpVariable. This has further advantages:

   • All the dynamic shape/stride information of the memref can be combined into a single descriptor. Descriptors are limited resources on many Vulkan hardware. So combining them would help make the generated code more portable across devices.
   • If the shape/stride information is small enough, they could be accessed using PushConstants that are faster to access and avoid buffer allocation overheads. These would be unnecessary if all shapes are static. In the dynamic shape cases, a few parameters are typically enough to compute the shape of all memrefs used/referenced within the kernel making the use of PushConstants possible.
   • The shape/stride information (typically) needs to be update less frequently than the data stored in the buffers. They could be part of different descriptor sets.

Contribution ¶

All kinds of contributions are highly appreciated! :) We have GitHub issues for tracking the dialect and lowering development. You can find todo tasks there. The Code organization section gives an overview of how SPIR-V related functionalities are implemented in MLIR. This section gives more concrete steps on how to contribute.

Automated development flow ¶

One of the goals of SPIR-V dialect development is to leverage both the SPIR-V human-readable specification and machine-readable grammar to auto-generate as much contents as possible. Specifically, the following tasks can be automated (partially or fully):

• Adding support for a new operation.
• Adding support for a new SPIR-V enum.
• Serialization and deserialization of a new operation.

We achieve this using the Python script gen_spirv_dialect.py. It fetches the human-readable specification and machine-readable grammar directly from the Internet and updates various SPIR-V *.td files in place. The script gives us an automated flow for adding support for new ops or enums.

Afterwards, we have SPIR-V specific mlir-tblgen backends for reading the Op Definition Spec and generate various components, including (de)serialization logic for ops. Together with standard mlir-tblgen backends, we auto-generate all op classes, enum classes, etc.

In the following subsections, we list the detailed steps to follow for common tasks.

Add a new op ¶

To add a new op, invoke the define_inst.sh script wrapper in utils/spirv. define_inst.sh requires a few parameters:

./define_inst.sh <filename> <base-class-name> <opname>

For example, to define the op for OpIAdd, invoke

./define_inst.sh SPIRVArithmeticOps.td ArithmeticBinaryOp OpIAdd

where SPIRVArithmeticOps.td is the filename for hosting the new op and ArithmeticBinaryOp is the direct base class the newly defined op will derive from.

Similarly, to define the op for OpAtomicAnd,

./define_inst.sh SPIRVAtomicOps.td AtomicUpdateWithValueOp OpAtomicAnd

Note that the generated SPIR-V op definition is just a best-effort template; it is still expected to be updated to have more accurate traits, arguments, and results.

It is also expected that a custom assembly form is defined for the new op, which will require providing the parser and printer. The EBNF form of the custom assembly should be described in the op’s description and the parser and printer should be placed in SPIRVOps.cpp with the following signatures:

static ParseResult parse<spirv-op-symbol>Op(OpAsmParser &parser,
                                            OperationState &state);
static void print(spirv::<spirv-op-symbol>Op op, OpAsmPrinter &printer);

See any existing op as an example.

Verification should be provided for the new op to cover all the rules described in the SPIR-V specification. Choosing the proper ODS types and attribute kinds, which can be found in SPIRVBase.td, can help here. Still sometimes we need to manually write additional verification logic in SPIRVOps.cpp in a function with the following signature:

LogicalResult spirv::<spirv-op-symbol>Op::verify();

See any such function in SPIRVOps.cpp as an example.

If no additional verification is needed, one needs to add the following to the op’s Op Definition Spec:

let hasVerifier = 0;

To suppress the requirement of the above C++ verification function.

Tests for the op’s custom assembly form and verification should be added to the proper file in test/Dialect/SPIRV/.

The generated op will automatically gain the logic for (de)serialization. However, tests still need to be coupled with the change to make sure no surprises. Serialization tests live in test/Dialect/SPIRV/Serialization.

Add a new enum ¶

To add a new enum, invoke the define_enum.sh script wrapper in utils/spirv. define_enum.sh expects the following parameters:

./define_enum.sh <enum-class-name>

For example, to add the definition for SPIR-V storage class in to SPIRVBase.td:

./define_enum.sh StorageClass

Add a new custom type ¶

SPIR-V specific types are defined in SPIRVTypes.h. See examples there and the tutorial for defining new custom types.

Add a new conversion ¶

To add conversion for a type update the mlir::spirv::SPIRVTypeConverter to return the converted type (must be a valid SPIR-V type). See Type Conversion for more details.

To lower an operation into SPIR-V dialect, implement a conversion pattern. If the conversion requires type conversion as well, the pattern must inherit from the mlir::spirv::SPIRVOpLowering class to get access to mlir::spirv::SPIRVTypeConverter. If the operation has a region, signature conversion might be needed as well.

Note: The current validation rules of spirv.module require that all operations contained within its region are valid operations in the SPIR-V dialect.

Operation definitions ¶

source

spirv.AccessChain (spirv::AccessChainOp) ¶

Create a pointer into a composite object.

Syntax:

operation ::= `spirv.AccessChain` $base_ptr `[` $indices `]` attr-dict `:` type($base_ptr) `,` type($indices) `->` type(results)

Result Type must be an OpTypePointer. Its Type operand must be the type reached by walking the Base’s type hierarchy down to the last provided index in Indexes, and its Storage Class operand must be the same as the Storage Class of Base.

Base must be a pointer, pointing to the base of a composite object.

Indexes walk the type hierarchy to the desired depth, potentially down to scalar granularity. The first index in Indexes will select the top- level member/element/component/element of the base composite. All composite constituents use zero-based numbering, as described by their OpType… instruction. The second index will apply similarly to that result, and so on. Once any non-composite type is reached, there must be no remaining (unused) indexes.

Each index in Indexes

• must be a scalar integer type,

• is treated as a signed count, and

• must be an OpConstant when indexing into a structure.

access-chain-op ::= ssa-id `=` `spirv.AccessChain` ssa-use
                    `[` ssa-use (',' ssa-use)* `]`
                    `:` pointer-type

Example: ¶

%0 = "spirv.Constant"() { value = 1: i32} : () -> i32
%1 = spirv.Variable : !spirv.ptr<!spirv.struct<f32, !spirv.array<4xf32>>, Function>
%2 = spirv.AccessChain %1[%0] : !spirv.ptr<!spirv.struct<f32, !spirv.array<4xf32>>, Function>
%3 = spirv.Load "Function" %2 ["Volatile"] : !spirv.array<4xf32>

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.mlir.addressof (spirv::AddressOfOp) ¶

Get the address of a global variable.

Syntax:

operation ::= `spirv.mlir.addressof` $variable attr-dict `:` type($pointer)

Variables in module scope are defined using symbol names. This op generates an SSA value that can be used to refer to the symbol within function scope for use in ops that expect an SSA value. This operation has no corresponding SPIR-V instruction; it’s merely used for modelling purpose in the SPIR-V dialect. Since variables in module scope in SPIR-V dialect are of pointer type, this op returns a pointer type as well, and the type is the same as the variable referenced.

Example: ¶

%0 = spirv.mlir.addressof @global_var : !spirv.ptr<f32, Input>

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Attributes: ¶

Results: ¶

spirv.AtomicAnd (spirv::AtomicAndOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicAnd` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value by the bitwise AND of Original Value and Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicAnd <Device> <None> %pointer, %value :
                   !spirv.ptr<i32, StorageBuffer>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicCompareExchange (spirv::AtomicCompareExchangeOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicCompareExchange` $memory_scope $equal_semantics $unequal_semantics operands attr-dict `:`
              type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value from Value only if Original Value equals Comparator, and

3. store the New Value back through Pointer’only if ‘Original Value equaled Comparator.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar.

Use Equal for the memory semantics of this instruction when Value and Original Value compare equal.

Use Unequal for the memory semantics of this instruction when Value and Original Value compare unequal. Unequal must not be set to Release or Acquire and Release. In addition, Unequal cannot be set to a stronger memory-order then Equal.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type. This type must also match the type of Comparator.

Memory is a memory Scope.

Example: ¶

%0 = spirv.AtomicCompareExchange <Workgroup> <Acquire> <None>
                                %pointer, %value, %comparator
                                : !spirv.ptr<i32, WorkGroup>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicCompareExchangeWeak (spirv::AtomicCompareExchangeWeakOp) ¶

Deprecated (use OpAtomicCompareExchange).

Syntax:

operation ::= `spirv.AtomicCompareExchangeWeak` $memory_scope $equal_semantics $unequal_semantics operands attr-dict `:`
              type($pointer)

Has the same semantics as OpAtomicCompareExchange.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicCompareExchangeWeak <Workgroup> <Acquire> <None>
                                   %pointer, %value, %comparator
                                   : !spirv.ptr<i32, WorkGroup>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicExchange (spirv::AtomicExchangeOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicExchange` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value from copying Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be a scalar of integer type or floating-point type.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type.

Memory is a memory Scope.

Example: ¶

%0 = spirv.AtomicExchange <Workgroup> <Acquire> %pointer, %value,
                        : !spirv.ptr<i32, WorkGroup>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicIAdd (spirv::AtomicIAddOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicIAdd` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value by integer addition of Original Value and Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicIAdd <Device> <None> %pointer, %value :
                    !spirv.ptr<i32, StorageBuffer>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicIDecrement (spirv::AtomicIDecrementOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicIDecrement` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value through integer subtraction of 1 from Original Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicIDecrement <Device> <None> %pointer :
                          !spirv.ptr<i32, StorageBuffer>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicIIncrement (spirv::AtomicIIncrementOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicIIncrement` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value through integer addition of 1 to Original Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicIncrement <Device> <None> %pointer :
                         !spirv.ptr<i32, StorageBuffer>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicISub (spirv::AtomicISubOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicISub` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value by integer subtraction of Value from Original Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicISub <Device> <None> %pointer, %value :
                    !spirv.ptr<i32, StorageBuffer>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicOr (spirv::AtomicOrOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicOr` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value by the bitwise OR of Original Value and Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicOr <Device> <None> %pointer, %value :
                  !spirv.ptr<i32, StorageBuffer>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicSMax (spirv::AtomicSMaxOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicSMax` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value by finding the largest signed integer of Original Value and Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicSMax <Device> <None> %pointer, %value :
                    !spirv.ptr<i32, StorageBuffer>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicSMin (spirv::AtomicSMinOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicSMin` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value by finding the smallest signed integer of Original Value and Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicSMin <Device> <None> %pointer, %value :
                    !spirv.ptr<i32, StorageBuffer>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicUMax (spirv::AtomicUMaxOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicUMax` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value by finding the largest unsigned integer of Original Value and Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicUMax <Device> <None> %pointer, %value :
                    !spirv.ptr<i32, StorageBuffer>

Traits: UnsignedOp

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicUMin (spirv::AtomicUMinOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicUMin` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value by finding the smallest unsigned integer of Original Value and Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicUMin <Device> <None> %pointer, %value :
                    !spirv.ptr<i32, StorageBuffer>

Traits: UnsignedOp

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.AtomicXor (spirv::AtomicXorOp) ¶

Perform the following steps atomically with respect to any other atomic accesses within Scope to the same location:

Syntax:

operation ::= `spirv.AtomicXor` $memory_scope $semantics operands attr-dict `:` type($pointer)

1. load through Pointer to get an Original Value,

2. get a New Value by the bitwise exclusive OR of Original Value and Value, and

3. store the New Value back through Pointer.

The instruction’s result is the Original Value.

Result Type must be an integer type scalar.

The type of Value must be the same as Result Type. The type of the value pointed to by Pointer must be the same as Result Type.

Memory must be a valid memory Scope.

Example: ¶

%0 = spirv.AtomicXor <Device> <None> %pointer, %value :
                   !spirv.ptr<i32, StorageBuffer>

Interfaces: InferTypeOpInterface, QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Attributes: ¶

Operands: ¶

Results: ¶

spirv.BitCount (spirv::BitCountOp) ¶

Count the number of set bits in an object.

Syntax:

operation ::= `spirv.BitCount` $operand `:` type($operand) attr-dict

Results are computed per component.

Result Type must be a scalar or vector of integer type. The components must be wide enough to hold the unsigned Width of Base as an unsigned value. That is, no sign bit is needed or counted when checking for a wide enough result width.

Base must be a scalar or vector of integer type. It must have the same number of components as Result Type.

The result is the unsigned value that is the number of bits in Base that are 1.

Example: ¶

%2 = spirv.BitCount %0: i32
%3 = spirv.BitCount %1: vector<4xi32>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.BitFieldInsert (spirv::BitFieldInsertOp) ¶

Make a copy of an object, with a modified bit field that comes from another object.

Syntax:

operation ::= `spirv.BitFieldInsert` operands attr-dict `:` type($base) `,` type($offset) `,` type($count)

Results are computed per component.

Result Type must be a scalar or vector of integer type.

The type of Base and Insert must be the same as Result Type.

Any result bits numbered outside [Offset, Offset + Count - 1] (inclusive) will come from the corresponding bits in Base.

Any result bits numbered in [Offset, Offset + Count - 1] come, in order, from the bits numbered [0, Count - 1] of Insert.

Count must be an integer type scalar. Count is the number of bits taken from Insert. It will be consumed as an unsigned value. Count can be 0, in which case the result will be Base.

Offset must be an integer type scalar. Offset is the lowest-order bit of the bit field. It will be consumed as an unsigned value.

The resulting value is undefined if Count or Offset or their sum is greater than the number of bits in the result.

Example: ¶

%0 = spirv.BitFieldInsert %base, %insert, %offset, %count : vector<3xi32>, i8, i8

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.BitFieldSExtract (spirv::BitFieldSExtractOp) ¶

Extract a bit field from an object, with sign extension.

Syntax:

operation ::= `spirv.BitFieldSExtract` operands attr-dict `:` type($base) `,` type($offset) `,` type($count)

Results are computed per component.

Result Type must be a scalar or vector of integer type.

The type of Base must be the same as Result Type.

If Count is greater than 0: The bits of Base numbered in [Offset, Offset

• Count - 1] (inclusive) become the bits numbered [0, Count - 1] of the result. The remaining bits of the result will all be the same as bit Offset + Count - 1 of Base.

Count must be an integer type scalar. Count is the number of bits extracted from Base. It will be consumed as an unsigned value. Count can be 0, in which case the result will be 0.

Offset must be an integer type scalar. Offset is the lowest-order bit of the bit field to extract from Base. It will be consumed as an unsigned value.

The resulting value is undefined if Count or Offset or their sum is greater than the number of bits in the result.

Example: ¶

%0 = spirv.BitFieldSExtract %base, %offset, %count : vector<3xi32>, i8, i8

Traits: AlwaysSpeculatableImplTrait, SignedOp

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.BitFieldUExtract (spirv::BitFieldUExtractOp) ¶

Extract a bit field from an object, without sign extension.

Syntax:

operation ::= `spirv.BitFieldUExtract` operands attr-dict `:` type($base) `,` type($offset) `,` type($count)

The semantics are the same as with OpBitFieldSExtract with the exception that there is no sign extension. The remaining bits of the result will all be 0.

Example: ¶

%0 = spirv.BitFieldUExtract %base, %offset, %count : vector<3xi32>, i8, i8

Traits: AlwaysSpeculatableImplTrait, UnsignedOp

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.BitReverse (spirv::BitReverseOp) ¶

Reverse the bits in an object.

Syntax:

operation ::= `spirv.BitReverse` $operand `:` type($operand) attr-dict

Results are computed per component.

Result Type must be a scalar or vector of integer type.

The type of Base must be the same as Result Type.

The bit-number n of the result will be taken from bit-number Width - 1 - n of Base, where Width is the OpTypeInt operand of the Result Type.

Example: ¶

%2 = spirv.BitReverse %0 : i32
%3 = spirv.BitReverse %1 : vector<4xi32>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.Bitcast (spirv::BitcastOp) ¶

Bit pattern-preserving type conversion.

Syntax:

operation ::= `spirv.Bitcast` $operand attr-dict `:` type($operand) `to` type($result)

Result Type must be an OpTypePointer, or a scalar or vector of numerical-type.

Operand must have a type of OpTypePointer, or a scalar or vector of numerical-type. It must be a different type than Result Type.

If either Result Type or Operand is a pointer, the other must be a pointer (diverges from the SPIR-V spec).

If Result Type has a different number of components than Operand, the total number of bits in Result Type must equal the total number of bits in Operand. Let L be the type, either Result Type or Operand’s type, that has the larger number of components. Let S be the other type, with the smaller number of components. The number of components in L must be an integer multiple of the number of components in S. The first component (that is, the only or lowest-numbered component) of S maps to the first components of L, and so on, up to the last component of S mapping to the last components of L. Within this mapping, any single component of S (mapping to multiple components of L) maps its lower- ordered bits to the lower-numbered components of L.

Example: ¶

%1 = spirv.Bitcast %0 : f32 to i32
%1 = spirv.Bitcast %0 : vector<2xf32> to i64
%1 = spirv.Bitcast %0 : !spirv.ptr<f32, Function> to !spirv.ptr<i32, Function>

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.BitwiseAnd (spirv::BitwiseAndOp) ¶

Result is 1 if both Operand 1 and Operand 2 are 1. Result is 0 if either Operand 1 or Operand 2 are 0.

Syntax:

operation ::= `spirv.BitwiseAnd` operands attr-dict `:` type($result)

Results are computed per component, and within each component, per bit.

Result Type must be a scalar or vector of integer type. The type of Operand 1 and Operand 2 must be a scalar or vector of integer type. They must have the same number of components as Result Type. They must have the same component width as Result Type.

Example: ¶

%2 = spirv.BitwiseAnd %0, %1 : i32
%2 = spirv.BitwiseAnd %0, %1 : vector<4xi32>

Traits: AlwaysSpeculatableImplTrait, Commutative, SameOperandsAndResultType, UsableInSpecConstantOp

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.BitwiseOr (spirv::BitwiseOrOp) ¶

Result is 1 if either Operand 1 or Operand 2 is 1. Result is 0 if both Operand 1 and Operand 2 are 0.

Syntax:

operation ::= `spirv.BitwiseOr` operands attr-dict `:` type($result)

Results are computed per component, and within each component, per bit.

Result Type must be a scalar or vector of integer type. The type of Operand 1 and Operand 2 must be a scalar or vector of integer type. They must have the same number of components as Result Type. They must have the same component width as Result Type.

Example: ¶

%2 = spirv.BitwiseOr %0, %1 : i32
%2 = spirv.BitwiseOr %0, %1 : vector<4xi32>

Traits: AlwaysSpeculatableImplTrait, Commutative, SameOperandsAndResultType, UsableInSpecConstantOp

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.BitwiseXor (spirv::BitwiseXorOp) ¶

Result is 1 if exactly one of Operand 1 or Operand 2 is 1. Result is 0 if Operand 1 and Operand 2 have the same value.

Syntax:

operation ::= `spirv.BitwiseXor` operands attr-dict `:` type($result)

Results are computed per component, and within each component, per bit.

Result Type must be a scalar or vector of integer type. The type of Operand 1 and Operand 2 must be a scalar or vector of integer type. They must have the same number of components as Result Type. They must have the same component width as Result Type.

Example: ¶

%2 = spirv.BitwiseXor %0, %1 : i32
%2 = spirv.BitwiseXor %0, %1 : vector<4xi32>

Traits: AlwaysSpeculatableImplTrait, Commutative, SameOperandsAndResultType, UsableInSpecConstantOp

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.BranchConditional (spirv::BranchConditionalOp) ¶

If Condition is true, branch to true block, otherwise branch to false block.

Condition must be a Boolean type scalar.

Branch weights are unsigned 32-bit integer literals. There must be either no Branch Weights or exactly two branch weights. If present, the first is the weight for branching to True Label, and the second is the weight for branching to False Label. The implied probability that a branch is taken is its weight divided by the sum of the two Branch weights. At least one weight must be non-zero. A weight of zero does not imply a branch is dead or permit its removal; branch weights are only hints. The two weights must not overflow a 32-bit unsigned integer when added together.

This instruction must be the last instruction in a block.

branch-conditional-op ::= `spirv.BranchConditional` ssa-use
                          (`[` integer-literal, integer-literal `]`)?
                          `,` successor `,` successor
successor ::= bb-id branch-use-list?
branch-use-list ::= `(` ssa-use-list `:` type-list-no-parens `)`

Example: ¶

spirv.BranchConditional %condition, ^true_branch, ^false_branch
spirv.BranchConditional %condition, ^true_branch(%0: i32), ^false_branch(%1: i32)

Traits: AlwaysSpeculatableImplTrait, AttrSizedOperandSegments, Terminator

Interfaces: BranchOpInterface, ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Attributes: ¶

Operands: ¶

Successors: ¶

spirv.Branch (spirv::BranchOp) ¶

Unconditional branch to target block.

Syntax:

operation ::= `spirv.Branch` $target (`(` $targetOperands^ `:` type($targetOperands) `)`)? attr-dict

This instruction must be the last instruction in a block.

Example: ¶

spirv.Branch ^target
spirv.Branch ^target(%0, %1: i32, f32)

Traits: AlwaysSpeculatableImplTrait, Terminator

Interfaces: BranchOpInterface, ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Successors: ¶

spirv.CL.acos (spirv::CLAcosOp) ¶

Compute the arc cosine of x.

Syntax:

operation ::= `spirv.CL.acos` $operand `:` type($operand) attr-dict

Result is an angle in radians.

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.acos %0 : f32
%3 = spirv.CL.acos %1 : vector<4xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.acosh (spirv::CLAcoshOp) ¶

Compute the inverse hyperbolic cosine of x .

Syntax:

operation ::= `spirv.CL.acosh` $operand `:` type($operand) attr-dict

Result is an angle in radians.

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.acosh %0 : f32
%3 = spirv.CL.acosh %1 : vector<4xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.asin (spirv::CLAsinOp) ¶

Compute the arc sine of x.

Syntax:

operation ::= `spirv.CL.asin` $operand `:` type($operand) attr-dict

Result is an angle in radians.

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.asin %0 : f32
%3 = spirv.CL.asin %1 : vector<4xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.asinh (spirv::CLAsinhOp) ¶

Compute the inverse hyperbolic sine of x.

Syntax:

operation ::= `spirv.CL.asinh` $operand `:` type($operand) attr-dict

Result is an angle in radians.

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.asinh %0 : f32
%3 = spirv.CL.asinh %1 : vector<4xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.atan2 (spirv::CLAtan2Op) ¶

Compute the arc tangent of y / x.

Syntax:

operation ::= `spirv.CL.atan2` operands attr-dict `:` type($result)

Result is an angle in radians.

Result Type, y and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.atan2 %0, %1 : f32
%3 = spirv.CL.atan2 %0, %1 : vector<4xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.atan (spirv::CLAtanOp) ¶

Compute the arc tangent of x.

Syntax:

operation ::= `spirv.CL.atan` $operand `:` type($operand) attr-dict

Result is an angle in radians.

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.atan %0 : f32
%3 = spirv.CL.atan %1 : vector<4xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.atanh (spirv::CLAtanhOp) ¶

Compute the hyperbolic arc tangent of x.

Syntax:

operation ::= `spirv.CL.atanh` $operand `:` type($operand) attr-dict

Result is an angle in radians.

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.atanh %0 : f32
%3 = spirv.CL.atanh %1 : vector<4xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.ceil (spirv::CLCeilOp) ¶

Round x to integral value using the round to positive infinity rounding mode.

Syntax:

operation ::= `spirv.CL.ceil` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.ceil %0 : f32
%3 = spirv.CL.ceil %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.cos (spirv::CLCosOp) ¶

Compute the cosine of x radians.

Syntax:

operation ::= `spirv.CL.cos` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.cos %0 : f32
%3 = spirv.CL.cos %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.cosh (spirv::CLCoshOp) ¶

Compute the hyperbolic cosine of x radians.

Syntax:

operation ::= `spirv.CL.cosh` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.cosh %0 : f32
%3 = spirv.CL.cosh %1 : vector<4xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.erf (spirv::CLErfOp) ¶

Error function of x encountered in integrating the normal distribution.

Syntax:

operation ::= `spirv.CL.erf` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.erf %0 : f32
%3 = spirv.CL.erf %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.exp (spirv::CLExpOp) ¶

Exponentiation of Operand 1

Syntax:

operation ::= `spirv.CL.exp` $operand `:` type($operand) attr-dict

Compute the base-e exponential of x. (i.e. ex)

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.exp %0 : f32
%3 = spirv.CL.exp %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.fabs (spirv::CLFAbsOp) ¶

Absolute value of operand

Syntax:

operation ::= `spirv.CL.fabs` $operand `:` type($operand) attr-dict

Compute the absolute value of x.

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.fabs %0 : f32
%3 = spirv.CL.fabs %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.fmax (spirv::CLFMaxOp) ¶

Return maximum of two floating-point operands

Syntax:

operation ::= `spirv.CL.fmax` operands attr-dict `:` type($result)

Returns y if x < y, otherwise it returns x. If one argument is a NaN, Fmax returns the other argument. If both arguments are NaNs, Fmax returns a NaN.

Result Type, x and y must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.fmax %0, %1 : f32
%3 = spirv.CL.fmax %0, %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.fmin (spirv::CLFMinOp) ¶

Return minimum of two floating-point operands

Syntax:

operation ::= `spirv.CL.fmin` operands attr-dict `:` type($result)

Returns y if y < x, otherwise it returns x. If one argument is a NaN, Fmin returns the other argument. If both arguments are NaNs, Fmin returns a NaN.

Result Type,x and y must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.fmin %0, %1 : f32
%3 = spirv.CL.fmin %0, %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.floor (spirv::CLFloorOp) ¶

Round x to the integral value using the round to negative infinity rounding mode.

Syntax:

operation ::= `spirv.CL.floor` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.floor %0 : f32
%3 = spirv.CL.floor %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.fma (spirv::CLFmaOp) ¶

Compute the correctly rounded floating-point representation of the sum of c with the infinitely precise product of a and b. Rounding of intermediate products shall not occur. Edge case results are per the IEEE 754-2008 standard.

Syntax:

operation ::= `spirv.CL.fma` operands attr-dict `:` type($result)

Result Type, a, b and c must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%0 = spirv.CL.fma %a, %b, %c : f32
%1 = spirv.CL.fma %a, %b, %c : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.log (spirv::CLLogOp) ¶

Compute the natural logarithm of x.

Syntax:

operation ::= `spirv.CL.log` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.log %0 : f32
%3 = spirv.CL.log %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.mix (spirv::CLMixOp) ¶

Returns the linear blend of x & y implemented as: x + (y - x) * a

Syntax:

operation ::= `spirv.CL.mix` operands attr-dict `:` type($result)

Result Type, x, y and a must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Note: This instruction can be implemented using contractions such as mad or fma.

Example: ¶

%0 = spirv.CL.mix %a, %b, %c : f32
%1 = spirv.CL.mix %a, %b, %c : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.pow (spirv::CLPowOp) ¶

Compute x to the power y.

Syntax:

operation ::= `spirv.CL.pow` operands attr-dict `:` type($result)

Result Type, x and y must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.pow %0, %1 : f32
%3 = spirv.CL.pow %0, %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.printf (spirv::CLPrintfOp) ¶

The printf extended instruction writes output to an implementation- defined stream such as stdout under control of the string pointed to by format that specifies how subsequent arguments are converted for output.

Syntax:

operation ::= `spirv.CL.printf` $format ( $arguments^ )? attr-dict `:`  type($format) ( `,` type($arguments)^ )? `->` type($result)

printf returns 0 if it was executed successfully and -1 otherwise.

Result Type must be i32.

Format must be a pointer(constant) to i8. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated (as always) but are otherwise ignored. The printf instruction returns when the end of the format string is encountered.

Example: ¶

%0 = spirv.CL.printf %fmt %1, %2  : !spirv.ptr<i8, UniformConstant>, i32, i32 -> i32

Interfaces: QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Operands: ¶

Results: ¶

spirv.CL.rint (spirv::CLRintOp) ¶

Round x to integral value (using round to nearest even rounding mode) in floating-point format.

Syntax:

operation ::= `spirv.CL.rint` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%0 = spirv.CL.rint %0 : f32
%1 = spirv.CL.rint %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.round (spirv::CLRoundOp) ¶

Return the integral value nearest to x rounding halfway cases away from zero, regardless of the current rounding direction.

Syntax:

operation ::= `spirv.CL.round` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.round %0 : f32
%3 = spirv.CL.round %0 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.rsqrt (spirv::CLRsqrtOp) ¶

Compute inverse square root of x.

Syntax:

operation ::= `spirv.CL.rsqrt` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.rsqrt %0 : f32
%3 = spirv.CL.rsqrt %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.s_abs (spirv::CLSAbsOp) ¶

Absolute value of operand

Syntax:

operation ::= `spirv.CL.s_abs` $operand `:` type($operand) attr-dict

Returns |x|, where x is treated as signed integer.

Result Type and x must be integer or vector(2,3,4,8,16) of integer values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.s_abs %0 : i32
%3 = spirv.CL.s_abs %1 : vector<3xi16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.s_max (spirv::CLSMaxOp) ¶

Return maximum of two signed integer operands

Syntax:

operation ::= `spirv.CL.s_max` operands attr-dict `:` type($result)

Returns y if x < y, otherwise it returns x, where x and y are treated as signed integers.

Result Type,x and y must be integer or vector(2,3,4,8,16) of integer values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.s_max %0, %1 : i32
%3 = spirv.CL.s_max %0, %1 : vector<3xi16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.s_min (spirv::CLSMinOp) ¶

Return minimum of two signed integer operands

Syntax:

operation ::= `spirv.CL.s_min` operands attr-dict `:` type($result)

Returns y if x < y, otherwise it returns x, where x and y are treated as signed integers.

Result Type,x and y must be integer or vector(2,3,4,8,16) of integer values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.s_min %0, %1 : i32
%3 = spirv.CL.s_min %0, %1 : vector<3xi16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.sin (spirv::CLSinOp) ¶

Compute sine of x radians.

Syntax:

operation ::= `spirv.CL.sin` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.sin %0 : f32
%3 = spirv.CL.sin %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.sinh (spirv::CLSinhOp) ¶

Compute hyperbolic sine of x radians.

Syntax:

operation ::= `spirv.CL.sinh` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.sinh %0 : f32
%3 = spirv.CL.sinh %1 : vector<4xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.sqrt (spirv::CLSqrtOp) ¶

Compute square root of x.

Syntax:

operation ::= `spirv.CL.sqrt` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.sqrt %0 : f32
%3 = spirv.CL.sqrt %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.tan (spirv::CLTanOp) ¶

Compute tangent of x radians.

Syntax:

operation ::= `spirv.CL.tan` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.tan %0 : f32
%3 = spirv.CL.tan %1 : vector<4xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.tanh (spirv::CLTanhOp) ¶

Compute hyperbolic tangent of x radians.

Syntax:

operation ::= `spirv.CL.tanh` $operand `:` type($operand) attr-dict

Result Type and x must be floating-point or vector(2,3,4,8,16) of floating-point values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.tanh %0 : f32
%3 = spirv.CL.tanh %1 : vector<3xf16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.u_max (spirv::CLUMaxOp) ¶

Return maximum of two unsigned integer operands

Syntax:

operation ::= `spirv.CL.u_max` operands attr-dict `:` type($result)

Returns y if x < y, otherwise it returns x, where x and y are treated as unsigned integers.

Result Type,x and y must be integer or vector(2,3,4,8,16) of integer values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.u_max %0, %1 : i32
%3 = spirv.CL.u_max %0, %1 : vector<3xi16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CL.u_min (spirv::CLUMinOp) ¶

Return minimum of two unsigned integer operands

Syntax:

operation ::= `spirv.CL.u_min` operands attr-dict `:` type($result)

Returns y if x < y, otherwise it returns x, where x and y are treated as unsigned integers.

Result Type,x and y must be integer or vector(2,3,4,8,16) of integer values.

All of the operands, including the Result Type operand, must be of the same type.

Example: ¶

%2 = spirv.CL.u_min %0, %1 : i32
%3 = spirv.CL.u_min %0, %1 : vector<3xi16>

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CompositeConstruct (spirv::CompositeConstructOp) ¶

Construct a new composite object from a set of constituent objects.

Syntax:

operation ::= `spirv.CompositeConstruct` $constituents attr-dict `:` `(` type(operands) `)` `->` type($result)

Result Type must be a composite type, whose top-level members/elements/components/columns have the same type as the types of the operands, with one exception. The exception is that for constructing a vector, the operands may also be vectors with the same component type as the Result Type component type. When constructing a vector, the total number of components in all the operands must equal the number of components in Result Type.

Constituents will become members of a structure, or elements of an array, or components of a vector, or columns of a matrix. There must be exactly one Constituent for each top-level member/element/component/column of the result, with one exception. The exception is that for constructing a vector, a contiguous subset of the scalars consumed can be represented by a vector operand instead. The Constituents must appear in the order needed by the definition of the type of the result. When constructing a vector, there must be at least two Constituent operands.

Example: ¶

%a = spirv.CompositeConstruct %1, %2, %3 : vector<3xf32>
%b = spirv.CompositeConstruct %a, %1 : (vector<3xf32>, f32) -> vector<4xf32>

%c = spirv.CompositeConstruct %1 :
  (f32) -> !spirv.coopmatrix<4x4xf32, Subgroup, MatrixA>

%d = spirv.CompositeConstruct %a, %4, %5 :
  (vector<3xf32>, !spirv.array<4xf32>, !spirv.struct<(f32)>) ->
    !spirv.struct<(vector<3xf32>, !spirv.array<4xf32>, !spirv.struct<(f32)>)>

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

spirv.CompositeExtract (spirv::CompositeExtractOp) ¶

Extract a part of a composite object.

Result Type must be the type of object selected by the last provided index. The instruction result is the extracted object.

Composite is the composite to extract from.

Indexes walk the type hierarchy, potentially down to component granularity, to select the part to extract. All indexes must be in bounds. All composite constituents use zero-based numbering, as described by their OpType… instruction.

composite-extract-op ::= ssa-id `=` `spirv.CompositeExtract` ssa-use
                         `[` integer-literal (',' integer-literal)* `]`
                         `:` composite-type

Example: ¶

%0 = spirv.Variable : !spirv.ptr<!spirv.array<4x!spirv.array<4xf32>>, Function>
%1 = spirv.Load "Function" %0 ["Volatile"] : !spirv.array<4x!spirv.array<4xf32>>
%2 = spirv.CompositeExtract %1[1 : i32] : !spirv.array<4x!spirv.array<4xf32>>

Traits: AlwaysSpeculatableImplTrait, UsableInSpecConstantOp

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Attributes: ¶

Operands: ¶

Results: ¶

spirv.CompositeInsert (spirv::CompositeInsertOp) ¶

Make a copy of a composite object, while modifying one part of it.

Result Type must be the same type as Composite.

Object is the object to use as the modified part.

Composite is the composite to copy all but the modified part from.

Indexes walk the type hierarchy of Composite to the desired depth, potentially down to component granularity, to select the part to modify. All indexes must be in bounds. All composite constituents use zero-based numbering, as described by their OpType… instruction. The type of the part selected to modify must match the type of Object.

composite-insert-op ::= ssa-id `=` `spirv.CompositeInsert` ssa-use, ssa-use
                        `[` integer-literal (',' integer-literal)* `]`
                        `:` object-type `into` composite-type

Example: ¶

%0 = spirv.CompositeInsert %object, %composite[1 : i32] : f32 into !spirv.array<4xf32>

Traits: AlwaysSpeculatableImplTrait, UsableInSpecConstantOp

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), QueryCapabilityInterface, QueryExtensionInterface, QueryMaxVersionInterface, QueryMinVersionInterface

Effects: MemoryEffects::Effect{}

Attributes: ¶

Operands: ¶

Results: ¶

spirv.Constant (spirv::ConstantOp) ¶

Declare a new integer-type or floating-point-type scalar constant.

This op declares a SPIR-V normal constant. SPIR-V has multiple constant instructions covering different constant types:

• OpConstantTrue and OpConstantFalse for boolean constants
• OpConstant for scalar constants
• OpConstantComposite for composite constants
• OpConstantNull for null constants
• …