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}