spirv_std/arch/
barrier.rs

1#[cfg(target_arch = "spirv")]
2use core::arch::asm;
3
4/// Wait for other invocations of this module to reach the current point
5/// of execution.
6///
7/// All invocations of this module within Execution scope reach this point of
8/// execution before any invocation proceeds beyond it.
9///
10/// When Execution is [`crate::memory::Scope::Workgroup`] or larger, behavior is
11/// undefined unless all invocations within Execution execute the same dynamic
12/// instance of this instruction. When Execution is Subgroup or Invocation, the
13/// behavior of this instruction in non-uniform control flow is defined by the
14/// client API.
15///
16/// If [`crate::memory::Semantics`] is not [`crate::memory::Semantics::NONE`],
17/// this instruction also serves as an [`memory_barrier`] function call, and
18/// also performs and adheres to the description and semantics of an
19/// [`memory_barrier`] function with the same `MEMORY` and `SEMANTICS` operands.
20/// This allows atomically specifying both a control barrier and a memory
21/// barrier (that is, without needing two instructions). If
22/// [`crate::memory::Semantics`] is [`crate::memory::Semantics::NONE`], `MEMORY`
23/// is ignored.
24///
25/// Before SPIRV-V version 1.3, it is only valid to use this instruction with
26/// `TessellationControl`, `GLCompute`, or `Kernel` execution models. There is
27/// no such restriction starting with version 1.3.
28///
29/// If used with the `TessellationControl` execution model, it also implicitly
30/// synchronizes the `output` storage class: Writes to `output` variables
31/// performed by any invocation executed prior to a [`control_barrier`] are
32/// visible to any other invocation proceeding beyond that [`control_barrier`].
33#[spirv_std_macros::gpu_only]
34#[doc(alias = "OpControlBarrier")]
35#[inline]
36pub fn control_barrier<
37    const EXECUTION: u32, // Scope
38    const MEMORY: u32,    // Scope
39    const SEMANTICS: u32, // Semantics
40>() {
41    unsafe {
42        asm! {
43            "%u32 = OpTypeInt 32 0",
44            "%execution = OpConstant %u32 {execution}",
45            "%memory = OpConstant %u32 {memory}",
46            "%semantics = OpConstant %u32 {semantics}",
47            "OpControlBarrier %execution %memory %semantics",
48            execution = const EXECUTION,
49            memory = const MEMORY,
50            semantics = const SEMANTICS,
51        }
52    }
53}
54
55/// Control the order that memory accesses are observed.
56///
57/// Ensures that memory accesses issued before this instruction are observed
58/// before memory accesses issued after this instruction. This control is
59/// ensured only for memory accesses issued by this invocation and observed by
60/// another invocation executing within `MEMORY` scope. If the `vulkan` memory
61/// model is declared, this ordering only applies to memory accesses that
62/// use the `NonPrivatePointer` memory operand or `NonPrivateTexel`
63/// image operand.
64///
65/// `SEMANTICS` declares what kind of memory is being controlled and what kind
66/// of control to apply.
67///
68/// To execute both a memory barrier and a control barrier,
69/// see [`control_barrier`].
70#[spirv_std_macros::gpu_only]
71#[doc(alias = "OpMemoryBarrier")]
72#[inline]
73pub fn memory_barrier<
74    const MEMORY: u32,    // Scope
75    const SEMANTICS: u32, // Semantics
76>() {
77    unsafe {
78        asm! {
79            "%u32 = OpTypeInt 32 0",
80            "%memory = OpConstant %u32 {memory}",
81            "%semantics = OpConstant %u32 {semantics}",
82            "OpMemoryBarrier %memory %semantics",
83            memory = const MEMORY,
84            semantics = const SEMANTICS,
85        }
86    }
87}
88
89/// Blocks execution of all threads in a group until all group shared accesses have been completed.
90///
91/// This is an exact implementation of `GroupMemoryBarrier()`.
92///
93/// From <https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/groupmemorybarrier>
94#[spirv_std_macros::gpu_only]
95#[inline]
96pub fn workgroup_memory_barrier() {
97    memory_barrier::<
98        { crate::memory::Scope::Workgroup as u32 },
99        {
100            crate::memory::Semantics::WORKGROUP_MEMORY.bits()
101                | crate::memory::Semantics::ACQUIRE_RELEASE.bits()
102        },
103    >();
104}
105
106/// Blocks execution of all threads in a group until all group shared accesses have been completed and all threads in the group have reached this call.
107///
108/// This is an exact implementation of `GroupMemoryBarrierWithGroupSync()`.
109///
110/// From <https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/groupmemorybarrierwithgroupsync>
111#[spirv_std_macros::gpu_only]
112#[inline]
113pub fn workgroup_memory_barrier_with_group_sync() {
114    control_barrier::<
115        { crate::memory::Scope::Workgroup as u32 },
116        { crate::memory::Scope::Workgroup as u32 },
117        {
118            crate::memory::Semantics::WORKGROUP_MEMORY.bits()
119                | crate::memory::Semantics::ACQUIRE_RELEASE.bits()
120        },
121    >();
122}
123
124/// Blocks execution of all threads in a group until all device memory accesses have been completed.
125///
126/// This is an exact implementation of `DeviceMemoryBarrier()`.
127///
128/// From <https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/devicememorybarrier>
129#[spirv_std_macros::gpu_only]
130#[inline]
131pub fn device_memory_barrier() {
132    memory_barrier::<
133        { crate::memory::Scope::Device as u32 },
134        {
135            crate::memory::Semantics::IMAGE_MEMORY.bits()
136                | crate::memory::Semantics::UNIFORM_MEMORY.bits()
137                | crate::memory::Semantics::ACQUIRE_RELEASE.bits()
138        },
139    >();
140}
141
142/// Blocks execution of all threads in a group until all device memory accesses have been completed and all threads in the group have reached this call.
143///
144/// This is an exact implementation of `DeviceMemoryBarrierWithGroupSync()`.
145///
146/// From <https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/devicememorybarrierwithgroupsync>
147#[spirv_std_macros::gpu_only]
148#[inline]
149pub fn device_memory_barrier_with_group_sync() {
150    control_barrier::<
151        { crate::memory::Scope::Workgroup as u32 },
152        { crate::memory::Scope::Device as u32 },
153        {
154            crate::memory::Semantics::IMAGE_MEMORY.bits()
155                | crate::memory::Semantics::UNIFORM_MEMORY.bits()
156                | crate::memory::Semantics::ACQUIRE_RELEASE.bits()
157        },
158    >();
159}
160
161/// Blocks execution of all threads in a group until all memory accesses have been completed.
162///
163/// This is an exact implementation of `AllMemoryBarrier()`.
164///
165/// From <https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/allmemorybarrier>
166#[spirv_std_macros::gpu_only]
167#[inline]
168pub fn all_memory_barrier() {
169    memory_barrier::<
170        { crate::memory::Scope::Device as u32 },
171        {
172            crate::memory::Semantics::WORKGROUP_MEMORY.bits()
173                | crate::memory::Semantics::IMAGE_MEMORY.bits()
174                | crate::memory::Semantics::UNIFORM_MEMORY.bits()
175                | crate::memory::Semantics::ACQUIRE_RELEASE.bits()
176        },
177    >();
178}
179
180/// Blocks execution of all threads in a group until all memory accesses have been completed and all threads in the group have reached this call.
181///
182/// This is an exact implementation of `AllMemoryBarrierWithGroupSync()`.
183///
184/// From <https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/allmemorybarrierwithgroupsync>
185#[spirv_std_macros::gpu_only]
186#[inline]
187pub fn all_memory_barrier_with_group_sync() {
188    control_barrier::<
189        { crate::memory::Scope::Workgroup as u32 },
190        { crate::memory::Scope::Device as u32 },
191        {
192            crate::memory::Semantics::WORKGROUP_MEMORY.bits()
193                | crate::memory::Semantics::IMAGE_MEMORY.bits()
194                | crate::memory::Semantics::UNIFORM_MEMORY.bits()
195                | crate::memory::Semantics::ACQUIRE_RELEASE.bits()
196        },
197    >();
198}