add documentation

Author: SimonDanisch

README.md

@@ -14,7 +14,9 @@ CUDAnative.jl is using (via LLVM + SPIR-V).
 
 # Why another GPU array package in yet another language?
 
-Julia offers countless advantages for a GPU array package.
+Julia offers great advantages for programming the GPU.
+This [blog post](http://mikeinnes.github.io/2017/08/24/cudanative.html) outlines a few of those.
+
 E.g., we can use Julia's JIT to generate optimized kernels for map/broadcast operations.
 
 This works even for things like complex arithmetic, since we can compile what's already in Julia Base.
@@ -45,15 +47,6 @@ Checkout the examples, to see how this can be used to emit specialized code whil
 In theory, we could go as far as inspecting user defined callbacks (we can get the complete AST), count operations and estimate register usage and use those numbers to optimize our kernels!
 
 
-### Automatic Differentiation
-
-Because of neural networks, automatic differentiation is super hyped right now!
-Julia offers a couple of packages for that, e.g. [ReverseDiff](https://github.com/JuliaDiff/ReverseDiff.jl).
-It heavily relies on Julia's strength to specialize generic code and dispatch to different implementations depending on the Array type, allowing an almost overheadless automatic differentiation.
-Making this work with GPUArrays will be a bit more involved, but the
-first [prototype](https://github.com/JuliaGPU/GPUArrays.jl/blob/master/examples/logreg.jl) looks already promising!
-There is also [ReverseDiffSource](https://github.com/JuliaDiff/ReverseDiffSource.jl), which should already work for simple functions.
-
 # Scope
 
 Current backends: OpenCL, CUDA, Julia Threaded
@@ -80,10 +73,33 @@ gemm!, scal!, gemv! and the high level functions that are implemented with these
 
 # Usage
 
+A backend will be initialized by default,
+but can be explicitly set with opencl(), cudanative(), threaded().
+There is also GPUArrays.init(device_symbol, filterfuncs...), which can be used to programatically
+initialize a backend.
+Filterfuncs can be used to select a device like this (`opencl()`, etc also support those):
+```Julia
+Pkg.init(:cudanative, is_gpu, dev-> has_atleast(dev, threads, 512))
+```
+You can also temporarily create a context on the currently selected backend with this construct:
+```Julia
+on_device([device = GPUArrays.current_device()]) do context
+    A = GPUArray(rand(Float32, 32, 32))
+    c = A .+ A
+end
+```
+Or you can run some code on all currently available devices like this:
+
+```Julia
+forall_devices(filterfuncs...) do context
+    A = GPUArray(rand(Float32, 32, 32))
+    c = A .+ A
+end
+```
+
+
 ```Julia
 using GPUArrays
-# A backend will be initialized by default on first call to the GPUArray constructor
-# But can be explicitely called like e.g.: CLBackend.init(), CUBackend.init(), JLBackend.init()
 
 a = GPUArray(rand(Float32, 32, 32)) # can be constructed from any Julia Array
 b = similar(a) # similar and other Julia.Base operations are defined
@@ -103,12 +119,12 @@ gpu_call(kernel::Function, DispatchDummy::GPUArray, args::Tuple, global_size = l
 with kernel looking like this:
 
 function kernel(state, arg1, arg2, arg3) # args get splatted into the kernel call
-    # state gets always passed as the first argument and is needed to offer the same 
+    # state gets always passed as the first argument and is needed to offer the same
     # functionality across backends, even though they have very different ways of of getting e.g. the thread index
     # arg1 can be any gpu array - this is needed to dispatch to the correct intrinsics.
-    # if you call gpu_call without any further modifications to global/local size, this should give you a linear index into 
+    # if you call gpu_call without any further modifications to global/local size, this should give you a linear index into
     # DispatchDummy
-    idx = linear_index(state, arg1::GPUArray) 
+    idx = linear_index(state, arg1::GPUArray)
     arg1[idx] = arg2[idx] + arg3[idx]
     return #kernel must return void
 end

src/backends/backends.jl

@@ -13,6 +13,7 @@ end
 
 #interface
 function create_buffer(ctx, array) end
+
 """
 Blocks until all operations are finished on `A`
 """
@@ -35,14 +36,39 @@ free(x::AbstractArray) = nothing
 #=
 Functions to select contexts
 =#
-
+"""
+Hardware threads of device
+"""
 threads(device) = 0
-blocks(device) = 0
+
+"""
+Blocks that group together hardware threads
+"""
+blocks(device) = 1
+"""
+Global memory, e.g. VRAM or RAM of device
+"""
 global_memory(device) = 0
+
+"""
+Free global memory. Isn't supported for AMD cards right now, in which case it returns NaN,
+so don't rely on the output of this function.
+"""
 free_global_memory(device) = NaN
+
+"""
+Block local memory
+"""
 local_memory(device) = 0
+
+"""
+Hardware name of a device
+"""
 name(device) = "Undefined"
 
+"""
+Summarizes all features of a device and prints it to `io`
+"""
 function device_summary(io::IO, device)
     println(io, "Device: ", name(device))
     for (n, f) in (:threads => threads, :blocks => blocks)
@@ -56,8 +82,20 @@ end
 
 ################################
 # Device selection functions for e.g. devices(filterfuncs)
+"""
+Returns true if `device` is a gpu
+"""
 is_gpu(device) = false
+
+"""
+Returns true if `device` is a cpu
+"""
 is_cpu(device) = false
+
+"""
+Checks a device for a certain attribute and returns true if it has at least `value`.
+Can be used with e.g. `threads`, `blocks`, `global_memory`, `local_memory`
+"""
 has_atleast(device, attribute, value) = attribute(ctx_or_device) >= value
 
 
@@ -74,12 +112,29 @@ is_cudanative(ctx) = false
 is_julia(ctx) = false
 is_opengl(ctx) = false
 
+const filterfuncs = """
+Device can be filtered by passing `filter_funcs`, e.g. :
+`is_gpu`, `is_cpu`, `(dev)-> has_atleast(dev, threads, 512)`
+"""
 
+"""
+Initializes the opencl backend with a default device.
+$filterfuncs
+"""
 opencl(filterfuncs...) = init(:opencl, filterfuncs...)
+
+"""
+Initializes the cudanative backend with a default device.
+$filterfuncs
+"""
 cudanative(filterfuncs...) = init(:cudanative, filterfuncs...)
+"""
+Initializes the threaded backend with a default device.
+$filterfuncs
+"""
 threaded(filterfuncs...) = init(:threaded, filterfuncs...)
 
-export opencl, cudanative, threaded
+
 
 """
 Creates a new context from `device` without caching the resulting context.
@@ -88,6 +143,13 @@ function new_context(device)
     error("Device $device not supported")
 end
 
+"""
+Destroys context, freeing all it's resources.
+"""
+function destroy!(context)
+    error("Device $context not supported")
+end
+
 """
 Resets a context freeing all resources and creating a new context.
 """
@@ -162,14 +224,17 @@ Context gets destroyed afterwards. Note, that creating a temporary context is ex
 """
 function on_device(f, device = current_device())
     ctx = new_context(device)
-    f(ctx)
-    destroy!(ctx)
+    try
+        f(ctx)
+    finally
+        destroy!(ctx)
+    end
     return
 end
 
 """
 Returns all devices for the current backend.
-Can be filtered by passing `filter_funcs`, e.g. `is_gpu`, `is_cpu`, `(dev)-> has_atleast(dev, threads, 512)`
+$filterfuncs
 """
 function available_devices(filter_funcs...)
     result = []
@@ -184,7 +249,7 @@ end
 
 """
 Returns all devices from `backends = active_backends()`.
-Can be filtered by passing `filter_funcs`, e.g. `is_gpu`, `is_cpu`, `dev-> has_atleast(dev, threads, 512)`
+$filterfuncs
 """
 function all_devices(filter_funcs...; backends = active_backends())
     result = []
@@ -198,15 +263,6 @@ function all_devices(filter_funcs...; backends = active_backends())
     result
 end
 
-"""
-Iterates through all backends and calls `f` after initializing the current one!
-"""
-function perbackend(f)
-    for backend in supported_backends()
-        ctx = GPUArrays.init(backend)
-        f(ctx)
-    end
-end
 
 """
 Iterates through all available devices and calls `f(context)` after initializing the standard context for that device.
@@ -219,4 +275,5 @@ function forall_devices(f, filterfuncs...)
 end
 
 
-export is_cudanative, is_julia, is_opencl
+export is_cudanative, is_julia, is_opencl, on_device
+export opencl, cudanative, threaded

src/backends/cudanative/cudanative.jl

@@ -83,7 +83,7 @@ let contexts = Dict{CUDAdrv.CuDevice, CUContext}(), active_device = CUDAdrv.CuDe
         ctx
     end
 
-    function destroy!(context::CUContext)
+    function GPUArrays.destroy!(context::CUContext)
         # don't destroy primary device context
         dev = context.device
         if haskey(contexts, dev) && contexts[dev] == context

src/backends/opencl/opencl.jl

@@ -77,7 +77,7 @@ let contexts = Dict{cl.Device, CLContext}(), active_device = cl.Device[]
         ctx
     end
 
-    function destroy!(context::CLContext)
+    function GPUArrays.destroy!(context::CLContext)
         # don't destroy primary device context
         dev = context.device
         if haskey(contexts, dev) && contexts[dev] == context