Add interface docs.

Author: maleadt

docs/make.jl

@@ -1,26 +1,30 @@
 using Documenter, GPUArrays
 
-makedocs(
-    modules = [GPUArrays],
-    format = Documenter.HTML(
-        # Use clean URLs on CI
-        prettyurls = get(ENV, "CI", nothing) == "true",
-        assets = ["assets/favicon.ico"],
-        analytics = "UA-154489943-6",
-    ),
-    sitename = "GPUArrays.jl",
-    pages = [
-        "Home"          => "index.md",
-        "Interface"     => "interface.md",
-        "Functionality" => [
-            "functionality/host.md",
-            "functionality/device.md",
+function main()
+    makedocs(
+        modules = [GPUArrays],
+        format = Documenter.HTML(
+            # Use clean URLs on CI
+            prettyurls = get(ENV, "CI", nothing) == "true",
+            assets = ["assets/favicon.ico"],
+            analytics = "UA-154489943-6",
+        ),
+        sitename = "GPUArrays.jl",
+        pages = [
+            "Home"          => "index.md",
+            "Interface"     => "interface.md",
+            "Functionality" => [
+                "functionality/host.md",
+                "functionality/device.md",
+            ],
+            "Test suite"    => "testsuite.md",
         ],
-        "Test suite"    => "testsuite.md",
-    ],
-    doctest = true,
-)
+        doctest = true,
+    )
 
-deploydocs(
-    repo = "github.com/JuliaGPU/GPUArrays.jl.git"
-)
+    deploydocs(
+        repo = "github.com/JuliaGPU/GPUArrays.jl.git"
+    )
+end
+
+isinteractive() || main()

docs/src/interface.md

@@ -1,6 +1,87 @@
 # Interface
 
-To extend the above functionality to a new array type, you should implement the following
-interfaces:
+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
+one that actually can be instantiated on the device (i.e. in kernels).
 
-TODO
+## Host-side
+
+Your host-side array type should build 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.unsafe_reinterpret
+```
+
+### Devices
+
+```@docs
+GPUArrays.device
+GPUArrays.synchronize
+```
+
+### Execution
+
+```@docs
+GPUArrays.AbstractGPUBackend
+GPUArrays.backend
+```
+
+```@docs
+GPUArrays._gpu_call
+```
+
+### Linear algebra
+
+```@docs
+GPUArrays.blas_module
+GPUArrays.blasbuffer
+```
+
+
+## Device-side
+
+To work with GPU memory on the device itself, e.g. within a kernel, we need a different
+type: Most functionality will behave differently when running on the GPU, e.g., accessing
+memory directly instead of copying it to the host. We should also take care not to call into
+any host library, such as the Julia runtime or the system's math library.
+
+```@docs
+AbstractDeviceArray
+```
+
+Your device array type should again implement the core elements of the `AbstractArray`
+interface, such as indexing and certain getters. Refer to the Julia manual for more details,
+or look at the `JLDeviceArray` reference implementation.
+
+You should also provide implementations of several "GPU intrinsics". To make sure the
+correct implementation is called, the first argument to these intrinsics will be the kernel
+state object from before.
+
+```@docs
+GPUArrays.LocalMemory
+GPUArrays.synchronize_threads
+GPUArrays.blockidx_x
+GPUArrays.blockidx_y
+GPUArrays.blockidx_z
+GPUArrays.blockdim_x
+GPUArrays.blockdim_y
+GPUArrays.blockdim_z
+GPUArrays.threadidx_x
+GPUArrays.threadidx_y
+GPUArrays.threadidx_z
+GPUArrays.griddim_x
+GPUArrays.griddim_y
+GPUArrays.griddim_z
+```

src/device/abstractarray.jl

@@ -5,6 +5,13 @@ export AbstractDeviceArray, @LocalMemory
 
 ## device array
 
+"""
+    AbstractDeviceArray{T, N}
+
+Supertype for `N`-dimensional GPU arrays (or array-like types) with elements of type `T`.
+This type is a subtype of `AbstractArray{T, N}`. Instances of this type are expected to live
+on the device, see [`AbstractGPUArray`](@ref) for device-side objects.
+"""
 abstract type AbstractDeviceArray{T, N} <: AbstractArray{T, N} end
 
 Base.IndexStyle(::AbstractDeviceArray) = IndexLinear()

src/host/abstractarray.jl

@@ -2,14 +2,19 @@
 
 export AbstractGPUArray
 
-abstract type AbstractGPUArray{T, N} <: DenseArray{T, N} end
+"""
+    AbstractGPUArray{T, N}
+
+Supertype for `N`-dimensional GPU arrays (or array-like types) with elements of type `T`.
+This type is a subtype of `AbstractArray{T, N}`. Instances of this type are expected to live
+on the host, see [`AbstractDeviceArray`](@ref) for device-side objects.
+"""
+abstract type AbstractGPUArray{T, N} <: AbstractArray{T, N} end
 
-# Sampler type that acts like a texture/image and allows interpolated access
-abstract type Sampler{T, N} <: DenseArray{T, N} end
+const AbstractGPUVector{T} = AbstractGPUArray{T, 1}
+const AbstractGPUMatrix{T} = AbstractGPUArray{T, 2}
+const AbstractGPUVecOrMat{T} = Union{AbstractGPUArray{T, 1}, AbstractGPUArray{T, 2}}
 
-const GPUVector{T} = AbstractGPUArray{T, 1}
-const GPUMatrix{T} = AbstractGPUArray{T, 2}
-const GPUVecOrMat{T} = Union{AbstractGPUArray{T, 1}, AbstractGPUArray{T, 2}}
 
 # input/output
 
@@ -216,8 +221,9 @@ DEALINGS IN THE SOFTWARE.
 import Base.reinterpret
 
 """
-Unsafe reinterpret for backends to overload.
-This makes it easier to do checks just on the high level.
+    unsafe_reinterpret(T, a, dims)
+
+Reinterpret the array `a` to have a new element type `T` and size `dims`.
 """
 function unsafe_reinterpret end
 

src/host/base.jl

@@ -54,12 +54,12 @@ function _sub2ind(inds, L, ind, i::IT, I::IT...) where IT
 end
 
 # This is pretty ugly, but I feel bad to add those to device arrays, since
-# we're never bound checking... So getindex(a::GPUVector, 10, 10) would silently go unnoticed
+# we're never bound checking... So getindex(a::AbstractGPUVector, 10, 10) would silently go unnoticed
 # we need this here for easier implementation of repeat
 @inline Base.@propagate_inbounds getidx_2d1d(x::AbstractVector, i, j) = x[i]
 @inline Base.@propagate_inbounds getidx_2d1d(x::AbstractMatrix, i, j) = x[i, j]
 
-function Base.repeat(a::GPUVecOrMat, m::Int, n::Int = 1)
+function Base.repeat(a::AbstractGPUVecOrMat, m::Int, n::Int = 1)
     o, p = size(a, 1), size(a, 2)
     b = similar(a, o*m, p*n)
     gpu_call(a, (b, a, o, p, m, n), n) do state, b, a, o, p, m, n
@@ -79,7 +79,7 @@ function Base.repeat(a::GPUVecOrMat, m::Int, n::Int = 1)
     return b
 end
 
-function Base.repeat(a::GPUVector, m::Int)
+function Base.repeat(a::AbstractGPUVector, m::Int)
     o = length(a)
     b = similar(a, o*m)
     gpu_call(a, (b, a, o, m), m) do state, b, a, o, m

src/host/linalg.jl

@@ -14,8 +14,8 @@ for elty in (Float32, Float64, ComplexF32, ComplexF64)
     @eval begin
         function BLAS.gemm!(
                 transA::AbstractChar, transB::AbstractChar, alpha::$T,
-                A::GPUVecOrMat{$elty}, B::GPUVecOrMat{$elty},
-                beta::$T, C::GPUVecOrMat{$elty}
+                A::AbstractGPUVecOrMat{$elty}, B::AbstractGPUVecOrMat{$elty},
+                beta::$T, C::AbstractGPUVecOrMat{$elty}
             )
             blasmod = blas_module(A)
             result = blasmod.gemm!(
@@ -56,7 +56,7 @@ end
 for elty in (Float32, Float64, ComplexF32, ComplexF64)
     T = VERSION >= v"1.3.0-alpha.115" ? :(Union{($elty), Bool}) : elty
     @eval begin
-        function BLAS.gemv!(trans::AbstractChar, alpha::$T, A::GPUVecOrMat{$elty}, X::GPUVector{$elty}, beta::$T, Y::GPUVector{$elty})
+        function BLAS.gemv!(trans::AbstractChar, alpha::$T, A::AbstractGPUVecOrMat{$elty}, X::AbstractGPUVector{$elty}, beta::$T, Y::AbstractGPUVector{$elty})
             m, n = size(A, 1), size(A, 2)
             if trans == 'N' && (length(X) != n || length(Y) != m)
                 throw(DimensionMismatch("A has dimensions $(size(A)), X has length $(length(X)) and Y has length $(length(Y))"))
@@ -92,7 +92,7 @@ end
 
 for elty in (Float32, Float64, ComplexF32, ComplexF64)
     @eval begin
-        function BLAS.gbmv!(trans::AbstractChar, m::Integer, kl::Integer, ku::Integer, alpha::($elty), A::GPUMatrix{$elty}, X::GPUVector{$elty}, beta::($elty), Y::GPUVector{$elty})
+        function BLAS.gbmv!(trans::AbstractChar, m::Integer, kl::Integer, ku::Integer, alpha::($elty), A::AbstractGPUMatrix{$elty}, X::AbstractGPUVector{$elty}, beta::($elty), Y::AbstractGPUVector{$elty})
             n = size(A, 2)
             if trans == 'N' && (length(X) != n || length(Y) != m)
                 throw(DimensionMismatch("A has dimensions $n, $m, X has length $(length(X)) and Y has length $(length(Y))"))

src/host/mapreduce.jl

@@ -9,7 +9,7 @@ Base.count(pred::Function, A::AbstractGPUArray) = Int(mapreduce(pred, +, A; init
 
 Base.:(==)(A::AbstractGPUArray, B::AbstractGPUArray) = Bool(mapreduce(==, &, A, B; init = true))
 
-LinearAlgebra.ishermitian(A::GPUMatrix) = acc_mapreduce(==, &, true, A, (adjoint(A),))
+LinearAlgebra.ishermitian(A::AbstractGPUMatrix) = acc_mapreduce(==, &, true, A, (adjoint(A),))
 
 # hack to get around of fetching the first element of the AbstractGPUArray
 # as a startvalue, which is a bit complicated with the current reduce implementation