Add SIMD docs & re-include installation tips (#807)

Author: pxl-th

Project.toml

@@ -1,7 +1,7 @@
 name = "AMDGPU"
 uuid = "21141c5a-9bdb-4563-92ae-f87d6854732e"
 authors = ["Julian P Samaroo <[email protected]>", "Valentin Churavy <[email protected]>", "Anton Smirnov <[email protected]>"]
-version = "1.3.6"
+version = "2.0.0"
 
 [deps]
 AbstractFFTs = "621f4979-c628-5d54-868e-fcf4e3e8185c"

docs/Project.toml

@@ -2,6 +2,7 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 GPUArrays = "0c68f7d7-f131-5f86-a1c3-88cf8149b2d7"
+SIMD = "fdea26ae-647d-5447-a871-4b548cad5224"
 
 [compat]
 Documenter = "1"

docs/make.jl

@@ -34,6 +34,7 @@ function main()
                 "Quick Start" => "tutorials/quickstart.md",
                 "Performance Tips" => "tutorials/perf.md",
                 "Profiling" => "tutorials/profiling.md",
+                "Installation Tips" => "install_tips.md",
             ],
             "API" => [
                 "Devices" => "api/devices.md",

docs/src/install_tips.md

@@ -1,20 +1,5 @@
 # Installation Info
 
-## Windows OS missing functionality
-
-Windows **does not** yet support [Hostcall](@ref), which means that
-some of the functionality does not work, like:
-
-- device printing;
-- dynamic memory allocation (from kernels).
-
-These hostcalls are sometimes launched when AMDGPU detects that a
-kernel might throw an exception, specifically during conversions, like:
-`Int32(1f0)`.
-
-To avoid this, use 'unsafe' conversion option:
-`unsafe_trunc(Int32, 1f0)`.
-
 ## ROCm system libraries
 
 On Linux, AMDGPU.jl queries the location of ROCm libraries through `rocminfo` by default.
@@ -104,10 +89,30 @@ hard_memory_limit = "none"
 # hard_memory_limit = "80 %"
 ```
 
+## Windows OS missing functionality
+
+Windows **does not** yet support [Hostcall](@ref), which means that
+some of the functionality does not work, like:
+
+- device printing;
+- dynamic memory allocation (from kernels).
+
+These hostcalls are sometimes launched when AMDGPU detects that a
+kernel might throw an exception, specifically during conversions, like:
+`Int32(1f0)`.
+
+To avoid this, use 'unsafe' conversion option:
+`unsafe_trunc(Int32, 1f0)`.
+
 ## Frequently-Asked-Questions
 
 ### Archlinux
 
-For the last few ROCM releases we have seen folks run into issue with the distro-provided builds of ROCM and associated tools. [#770](https://github.com/JuliaGPU/AMDGPU.jl/issues/770), [#696](https://github.com/JuliaGPU/AMDGPU.jl/issues/696), [#767](https://github.com/JuliaGPU/AMDGPU.jl/issues/767)
+For the last few ROCM releases we have seen folks run into
+issue with the distro-provided builds of ROCM and associated tools.
+[#770](https://github.com/JuliaGPU/AMDGPU.jl/issues/770),
+[#696](https://github.com/JuliaGPU/AMDGPU.jl/issues/696),
+[#767](https://github.com/JuliaGPU/AMDGPU.jl/issues/767)
 
-Some users have reported success with using the [`opencl-amd-dev`](https://aur.archlinux.org/packages/opencl-amd-dev) AUR package. 
+Some users have reported success with using the
+[`opencl-amd-dev`](https://aur.archlinux.org/packages/opencl-amd-dev) AUR package.

docs/src/tutorials/perf.md

@@ -44,3 +44,62 @@ julia> GPUArrays.unsafe_free!(cache)
 For a more sophisticated real-world example, see how
 [GaussianSplatting.jl](https://github.com/JuliaNeuralGraphics/GaussianSplatting.jl/blob/e4ef1324c187371e336bef875b053023afe7fb2c/src/training.jl#L183)
 handles it.
+
+## Using SIMD
+
+Using vectorized load/store instructions can improve performance of the kernel.
+Let's see on a simple vector addition example how to use it.
+
+We define two helper functions:
+- `vload` that will load SIMD tile given a pointer into the array;
+- `vstore!` that will write SIMD tile into an array given its pointer.
+
+```@example vadd-simd
+using AMDGPU, SIMD
+
+@inline function vload(::Type{SIMD.Vec{N, T}}, ptr::Core.LLVMPtr{T, AS}) where {N, T, AS}
+    alignment = sizeof(T) * N
+    vec_ptr = Base.bitcast(Core.LLVMPtr{SIMD.Vec{N, T}, AS}, ptr)
+    return unsafe_load(vec_ptr, 1, Val(alignment))
+end
+
+@inline function vstore!(ptr::Core.LLVMPtr{T, AS}, x::SIMD.Vec{N, T}) where {N, T, AS}
+    alignment = sizeof(T) * N
+    vec_ptr = Base.bitcast(Core.LLVMPtr{SIMD.Vec{N, T}, AS}, ptr)
+    unsafe_store!(vec_ptr, x, 1, Val(alignment))
+    return
+end
+
+function vadd_simd!(c::AbstractVector{T}, a, b, ::Val{tile_size}) where {T, tile_size}
+    i = workitemIdx().x + (workgroupIdx().x - 1) * workgroupDim().x
+    tile_idx = (i - 1) * tile_size + 1
+
+    a_ptr = pointer(a, tile_idx)
+    b_ptr = pointer(b, tile_idx)
+    c_ptr = pointer(c, tile_idx)
+
+    a_tile = vload(SIMD.Vec{tile_size, T}, a_ptr)
+    b_tile = vload(SIMD.Vec{tile_size, T}, b_ptr)
+    vstore!(c_ptr, a_tile + b_tile)
+    return
+end
+
+n = 1024
+tile_size = Val(4)
+
+a = ROCArray(ones(Int, n))
+b = ROCArray(ones(Int, n))
+c = ROCArray(zeros(Int, n))
+
+groupsize = 256
+gridsize = cld(length(c), groupsize)
+@roc groupsize=groupsize gridsize=gridsize vadd_simd!(c, a, b, tile_size)
+@assert c == (a .+ b)
+```
+
+Examining LLVM IR, we can see vectorized `load <4 x i64>`, `add <4 x i64>`
+and `store <4 x i64>` instructions:
+
+```@example vadd-simd
+AMDGPU.@device_code_llvm @roc launch=false vadd_simd!(c, a, b, tile_size);
+```