Add Buffer Device Address chapter (#275)

Author: spencer-lunarg

README.adoc

@@ -158,6 +158,12 @@ The Vulkan Guide can be built as a single page using `asciidoctor guide.adoc`
 
 // include::{chapters}protected.adoc[]
 
+=== xref:{chapters}buffer_device_address.adoc[Buffer Device Address]
+
+// include::{chapters}buffer_device_address.adoc[]
+
+  * `VK_KHR_buffer_device_address`, `VK_EXT_buffer_device_address`
+
 == xref:{chapters}pipeline_cache.adoc[Pipeline Caching/Derivatives]
 
 // include::{chapters}pipeline_cache.adoc[]

chapters/buffer_device_address.adoc

@@ -0,0 +1,184 @@
+// Copyright 2024 The Khronos Group, Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+// Required for both single-page and combined guide xrefs to work
+ifndef::chapters[:chapters:]
+ifndef::images[:images: images/]
+
+[[buffer-device-address]]
+= Buffer Device Address
+
+Buffer Device Address allows you to have a pointer to the `VkBuffer` in your shaders. There are many other usages such as Ray Tracing, GPU Side tooling, etc.
+
+[NOTE]
+====
+This will be more of a technical breakdown of how it works, if you looking for a simple "how do I just use this", then please take a look at the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/extensions/buffer_device_address[Vulkan Samples].
+====
+
+== Extension
+
+The original proposal was done with the  `VK_EXT_buffer_device_address` extension. Shortly afterwards, `VK_KHR_buffer_device_address` was added, which had some minor feature differences. Starting in Vulkan 1.2 this has become core and it is very widely available on GPUs on every platform. Starting in Vulkan 1.3 it became required, so if you are using Vulkan 1.3, you are guaranteed support.
+
+=== Name alias
+
+The naming of this `Buffer Device Address` feature will be different depending on where you look.
+
+For GLSL, it is `buffer reference` (see link:https://github.com/KhronosGroup/GLSL/blob/main/extensions/ext/GLSL_EXT_buffer_reference.txt[GL_EXT_buffer_reference]). This is because syntactically it's used more like a C++ reference than a pointer.
+
+For SPIR-V, it is `PhysicalStorageBuffer` (see link:https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/main/extensions/KHR/SPV_KHR_physical_storage_buffer.html[SPV_KHR_physical_storage_buffer]). The name comes from the fact there was a `StorageBuffer` and now it is "Physical". (`Physical` is from "physical addressing" which is a concept in `Kernel` SPIR-V)
+
+If you are coming from DirectX, you will know the feature as `GPU virtual address`.
+
+== Vulkan Side
+
+From the Vulkan code, the only 3 things you need to do is
+
+1. Enable the `bufferDeviceAddress` feature. (Also the extension if using Vulkan 1.0 or 1.1)
+2. Add `VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_KHR` when creating your `VkBuffer`.
+3. Add `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR` when allocating your `VkDeviceMemory`.
+
+From here you can use the `vkGetBufferDeviceAddress` call and it will return a `VkDeviceAddress`. This is now your 64-bit pointer to that `VkBuffer` that can be handed down into your shader.
+
+[NOTE]
+====
+For tools, the `vkGetBufferDeviceAddress` function might break assumptions that Vulkan function only return `void` or `VkResult`
+====
+
+== SPIR-V Side
+
+[NOTE]
+====
+If you are using GLSL/HLSL/Slang/etc then the following is all taken care for you!
+====
+
+=== Capability
+
+The SPIR-V will contain the `OpCapability PhysicalStorageBufferAddresses` instruction that will match up with `VkPhysicalDeviceVulkan12Features::bufferDeviceAddress` (or `VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddress`) to let everyone know the device does support this.
+
+=== Addressing Model
+
+SPIR-V has an link:https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#Addressing_Model[Addressing Model] that has 3 group of options
+
+1. `Logical` - this is what Vulkan 1.0 uses, it has no concept of pointers
+2. `Physical32`/`Physical64` - this for OpenCL
+3. `PhysicalStorageBuffer64` - this is what you will use if you are making use of Buffer Device Address
+
+=== shaderInt64
+
+Since these `VkDeviceAddress` are represented as 64-bit integer pointers in your shader, you will likely want `shaderInt64` support for your device.
+
+Some device migth support `bufferDeviceAddress`, but not `shaderInt64`. The way around this situation is to make everything an `uvec2` (see link:https://github.com/KhronosGroup/GLSL/blob/main/extensions/ext/GLSL_EXT_buffer_reference_uvec2.txt[GL_EXT_buffer_reference_uvec2]).
+
+=== Alignment
+
+All variables accessed with `PhysicalStorageBuffer` must have an `Aligned` memory operand to it.
+
+[source,swift]
+----
+%x = OpLoad %type %ptr Aligned 16
+OpStore %ptr %obj Aligned 16
+----
+
+Shading languages will have a default, but can allow you to align it explicitly (ex `buffer_reference_alignment`).
+
+The goal of this alignment is this is a promise for how aligned this specific pointer is. The user is responsible to confirm the address they use is aligned to it.
+
+=== Nullptr
+
+SPIR-V has a `OpConstantNull`, but that can't be used with `PhysicalStorageBuffer`. The way around this is to either convert the pointer to an integer with `OpConvertPtrToU` or to a `uvec2` with `OpBitcast`.
+
+Vulkan defines the integer value of `0` to be null (as everyone would hopefully expect!).
+
+=== Cross stage variables
+
+There is still on-going discussion to clarify if/how passing pointers from two stages works (ex. vertex to fragment).
+
+The main issue is you may get validation layers errors with the `Location` matching (see https://github.com/KhronosGroup/Vulkan-ValidationLayers/pull/5349).
+
+The suggestion is to just pass a `uvec2` or `int64` across stages and re-cast it in your consumer stage.
+
+=== OpTypeForwardPointer and infinite loops
+
+The `OpTypeForwardPointer` is used to forward reference the type of the pointer. This is useful if the app wants to do something like a linked-list
+
+[source,glsl]
+----
+layout(buffer_reference) buffer Node;
+
+layout(buffer_reference, std430) buffer Node {
+    Node next_node;
+    int payload;
+};
+
+layout(set = 0, binding = 0, std430) buffer SSBO {
+    Node start;
+};
+----
+
+You will see the following SPIR-V
+
+[source,swift]
+----
+            OpTypeForwardPointer %Node_ptr PhysicalStorageBuffer
+    %SSBO = OpTypeStruct %Node_ptr
+     %int = OpTypeInt 32 1
+    %Node = OpTypeStruct %Node_ptr %int
+%Node_ptr = OpTypePointer PhysicalStorageBuffer %Node
+%SSBO_ptr = OpTypePointer StorageBuffer %SSBO
+     %var = OpVariable %SSBO_ptr StorageBuffer
+----
+
+When parsing this SPIR-V to do reflection, it is very easy to get into an infinite loop, so be careful.
+
+[NOTE]
+====
+If you want some SPIR-V to test this, look at the `buffer_handle_*.spv` tests in link:https://github.com/KhronosGroup/SPIRV-Reflect/blob/main/tests/glsl[SPIR-V Reflect Tests].
+====
+
+=== Accesses
+
+If you take the following simple GLSL example
+
+[source,glsl]
+----
+#version 450
+#extension GL_EXT_buffer_reference : enable
+
+layout(buffer_reference) buffer BDA {
+    int a;
+};
+
+layout(set=0, binding=0) uniform InData {
+    BDA b;
+};
+
+void main() {
+    b.a = 0;
+}
+----
+
+You will see the following SPIR-V
+
+[source,swift]
+----
+%bda_ptr = OpTypePointer PhysicalStorageBuffer %bda_struct
+%ubo_ptr = OpTypePointer Uniform %bda_ptr
+%int_ptr = OpTypePointer PhysicalStorageBuffer %type_int
+
+ %1 = OpAccessChain %ubo_ptr %3 %int_0
+ %2 = OpLoad %bda_ptr %1
+ %3 = OpAccessChain %int_ptr %2 %int_0
+      OpStore %3 %int_0 Aligned 16
+----
+
+It is easy to think that this `OpLoad` here is dereferencing the pointer before we store into it.
+
+This assumption is wrong, and instead the `OpLoad` is loading the logical pointer from the `ubo`. The access chain is computing an offset from that to the physical pointer. From here, the `OpStore` access the right location in memory through the pointer.
+
+Therefore in the above example, there is only a write access to that memory.
+
+== Overview
+
+The following diagram tries to capture visually how Buffer Device Address works
+
+image::{images}buffer_device_address_overview.png[buffer_device_address_overview.png]

chapters/images/buffer_device_address_overview.png

@@ -157,6 +157,10 @@ include::{chapters}sparse_resources.adoc[]
 
 include::{chapters}protected.adoc[]
 
+// === Buffer Device Address
+
+include::{chapters}buffer_device_address.adoc[]
+
 // == Pipeline Caching/Derivatives
 
 include::{chapters}pipeline_cache.adoc[]

guide.adoc

@@ -144,6 +144,12 @@ Vulkan Guide は、`asciidoctor guide.adoc` を使って1つのページとし
 
 // include::{chapters}protected.adoc[]
 
+=== xref:{chapters}buffer_device_address.adoc[Buffer Device Address]
+
+// include::{chapters}buffer_device_address.adoc[]
+
+  * `VK_KHR_buffer_device_address`, `VK_EXT_buffer_device_address`
+
 == xref:{chapters}pipeline_cache.adoc[パイプライン キャッシング/派生]
 
 // include::{chapters}pipeline_cache.adoc[]

lang/jp/README-jp.adoc

@@ -0,0 +1,11 @@
+// Copyright 2024 The Khronos Group, Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+// Required for both single-page and combined guide xrefs to work
+ifndef::chapters[:chapters:]
+ifndef::images[:images: images/]
+
+[[buffer-device-address]]
+= Buffer Device Address
+
+すみません！まだまだ翻訳が必要！

lang/jp/chapters/buffer_device_address.adoc

@@ -150,6 +150,10 @@ include::{chapters}sparse_resources.adoc[]
 
 include::{chapters}protected.adoc[]
 
+// === Buffer Device Address
+
+include::{chapters}buffer_device_address.adoc[]
+
 // == Pipeline Caching/Derivatives
 
 include::{chapters}pipeline_cache.adoc[]

lang/jp/guide.adoc

@@ -159,6 +159,12 @@ Vulkan에서 사용하는 특수한 용어에 대한 혼란을 막기 위해 명
 
 // include::{chapters}protected.adoc[]
 
+=== xref:{chapters}buffer_device_address.adoc[Buffer Device Address]
+
+// include::{chapters}buffer_device_address.adoc[]
+
+  * `VK_KHR_buffer_device_address`, `VK_EXT_buffer_device_address`
+
 == xref:{chapters}pipeline_cache.adoc[파이프라인 캐싱/파생]
 
 // include::{chapters}pipeline_cache.adoc[]

lang/kor/README-kor.adoc

@@ -0,0 +1,11 @@
+// Copyright 2024 The Khronos Group, Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+// Required for both single-page and combined guide xrefs to work
+ifndef::chapters[:chapters:]
+ifndef::images[:images: images/]
+
+[[buffer-device-address]]
+= Buffer Device Address
+
+죄송합니다, 아직 번역이 필요합니다.

lang/kor/chapters/buffer_device_address.adoc

@@ -153,6 +153,10 @@ include::{chapters}sparse_resources.adoc[]
 
 include::{chapters}protected.adoc[]
 
+// === Buffer Device Address
+
+include::{chapters}buffer_device_address.adoc[]
+
 // == Pipeline Caching/Derivatives
 
 include::{chapters}pipeline_cache.adoc[]