diff --git a/docs/src/index.md b/docs/src/index.md index cfdd3272..8cb100ca 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -9,10 +9,9 @@ will get a lot of functionality for free. This will allow to have multiple GPUAr implementation for different purposes, while maximizing the ability to share code. **This package is not intended for end users!** Instead, you should use one of the packages -that builds on GPUArrays.jl. There is currently only a single package that actively builds -on these interfaces, namely [CuArrays.jl](https://github.com/JuliaGPU/CuArrays.jl). +that builds on GPUArrays.jl such as [CUDA](https://github.com/JuliaGPU/CUDA.jl), [AMDGPU](https://github.com/JuliaGPU/AMDGPU.jl), [OneAPI](https://github.com/JuliaGPU/oneAPI.jl), or [Metal](https://github.com/JuliaGPU/Metal.jl). -In this documentation, you will find more information on the interface that you are expected +This documentation is meant for users who might wish to implement a version of GPUArrays for another GPU backend and will cover the features you will need to implement, the functionality you gain by doing so, and the test suite that is available to verify your implementation. GPUArrays.jl also provides a reference implementation of these interfaces on the CPU: The `JLArray` array type uses Julia's parallel programming diff --git a/docs/src/interface.md b/docs/src/interface.md index 44f62405..239bef87 100644 --- a/docs/src/interface.md +++ b/docs/src/interface.md @@ -1,51 +1,32 @@ # Interface To extend the above functionality to a new array type, you should use the types and -implement the interfaces listed on this page. GPUArrays is design around having two -different array types to represent a GPU array: one that only ever lives on the host, and +implement the interfaces listed on this page. GPUArrays is designed around having two +different array types to represent a GPU array: one that exists only on the host, and one that actually can be instantiated on the device (i.e. in kernels). +Device functionality is then handled by [KernelAbstractions.jl](https://github.com/JuliaGPU/KernelAbstractions.jl). +## Host abstractions -## Device functionality - -Several types and interfaces are related to the device and execution of code on it. First of -all, you need to provide a type that represents your execution back-end and a way to call -kernels: +You should provide an array type that builds on the `AbstractGPUArray` supertype, such as: -```@docs -GPUArrays.gpu_call -GPUArrays.thread_block_heuristic ``` +mutable struct CustomArray{T, N} <: AbstractGPUArray{T, N} + data::DataRef{Vector{UInt8}} + offset::Int + dims::Dims{N} + ... +end -You then need to provide implementations of certain methods that will be executed on the -device itself: - -```@docs -GPUArrays.AbstractDeviceArray -GPUArrays.LocalMemory -GPUArrays.synchronize_threads -GPUArrays.blockidx -GPUArrays.blockdim -GPUArrays.threadidx -GPUArrays.griddim ``` +This will allow your defined type (in this case `JLArray`) to use the GPUArrays interface where available. +To be able to actually use the functionality that is defined for `AbstractGPUArray`s, you need to define the backend, like so: -## Host abstractions - -You should provide an array type that builds on the `AbstractGPUArray` supertype: - -```@docs -AbstractGPUArray ``` - -First of all, you should implement operations that are expected to be defined for any -`AbstractArray` type. Refer to the Julia manual for more details, or look at the `JLArray` -reference implementation. - -To be able to actually use the functionality that is defined for `AbstractGPUArray`s, you -should provide implementations of the following interfaces: - -```@docs -GPUArrays.backend +import KernelAbstractions: Backend +struct CustomBackend <: KernelAbstractions.GPU +KernelAbstractions.get_backend(a::CA) where CA <: CustomArray = CustomBackend() ``` + +There are numerous examples of potential interfaces for GPUArrays, such as with [JLArrays](https://github.com/JuliaGPU/GPUArrays.jl/blob/master/lib/JLArrays/src/JLArrays.jl), [CuArrays](https://github.com/JuliaGPU/CUDA.jl/blob/master/src/gpuarrays.jl), and [ROCArrays](https://github.com/JuliaGPU/AMDGPU.jl/blob/master/src/gpuarrays.jl).