Merge pull request #2 from JuliaGPU/vc/docs

Cleanup docs and remove ScalarCPU

Author: vchuravy

.travis.yml

@@ -1,5 +1,8 @@
 ## Documentation: http://docs.travis-ci.com/user/languages/julia/
 language: julia
+branches:
+  only:
+  - master
 os:
   - linux
   - osx

docs/make.jl

@@ -2,14 +2,20 @@ using Documenter, KernelAbstractions
 
 makedocs(
     modules = [KernelAbstractions],
-    sitename = "KernelAbstractions.jl",
+    sitename = "KernelAbstractions",
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true"
     ),
     pages = [
-        "Home"    => "index.md",
-        "Kernel Language" => "kernels.md",
-        "Design" => "design.md"
+        "Home" => "index.md",
+        "Writing kernels" => "kernels.md",
+        "Examples" => [
+            "examples/memcopy.md"
+        ],
+        "API"          => "api.md",
+        "Extras" => [
+            "extras/unrolling.md"
+        ]
     ],
     doctest = true
 )

docs/src/api.md

@@ -0,0 +1,21 @@
+# API
+
+## [Kernel language](@id api_kernel_language)
+
+```@docs
+@kernel
+@Const
+@index
+@localmem
+@private
+@synchronize
+```
+
+## Host interface
+
+## Internal
+
+```@docs
+KernelAbstractions.Kernel
+KernelAbstractions.partition
+```

docs/src/examples/memcopy.md

@@ -0,0 +1,14 @@
+# Memcopy
+
+The first example simple copies memory from `A` to `B`
+
+````@eval
+using Markdown
+using KernelAbstractions
+path = joinpath(dirname(pathof(KernelAbstractions)), "..", "examples/memcopy.jl")
+Markdown.parse("""
+```julia
+$(read(path, String))
+```
+""")
+````

docs/src/extras/unrolling.md

@@ -0,0 +1,9 @@
+# Unroll macro
+
+```@meta
+CurrentModule = KernelAbstractions.Extras
+```
+
+```@docs
+@unroll
+```

docs/src/index.md

@@ -1,40 +1,70 @@
-# KernelAbstractions.jl
+# KernelAbstractions
 
-```@contents
-```
+`KernelAbstractions.jl` is a package that allows you to write GPU-like kernels that
+target different execution backends. It is intended to be a minimal, and performant
+library that explores ways to best write heterogenous code.
 
-## Kernel functions 
+!!! note
+    While `KernelAbstraction.jl` is focused on performance portatbility, it is GPU-biased
+    and therefore the kernel language has several constructs that are necessary for good
+    performance on the GPU, but may hurt performance on the CPU.
 
-```@docs
-@kernel
-```
+## Quickstart
 
-### Marking input arguments as constant
+### Writing your first kernel
 
-```@docs
-@Const
+Kernel functions have to be marked with the [`@kernel`](@ref). Inside the `@kernel` macro
+you can use the [kernel language](@ref api_kernel_language). As an example the `mul2` kernel
+below will multiply each element of the array `A` by `2`. It uses the [`@index`](@ref) macro
+to obtain the global linear index of the current workitem.
+
+```julia
+@kernel function mul2(A)
+  I = @index(Global)
+  A[I] = 2 * A[I]
+end
 ```
 
-## Important difference to Julia
+### Launching your first kernel
+
+You can construct a kernel for a specific backend by calling the kernel function
+with the first argument being the device kind, the second argument being the size
+of the workgroup and the third argument being a static `ndrange`. The second and
+third argument are optional. After instantiating the kernel you can launch it by
+calling the kernel object with the right arguments and some keyword arguments that
+configure the specific launch. The example below creates a kernel with a static
+workgroup size of `16` and a dynamic `ndrange`. Since the `ndrange` is dynamic it
+has to be provided for the launch as a keyword argument.
+
+```julia
+A = ones(1024, 1024)
+kernel = mul2(CPU(), 16)
+event = kernel(A, ndrange=size(A))
+wait(event)
+all(A .== 2.0)
+```
 
-- Functions inside kernels are forcefully inlined, except when marked with `@noinline`
-- Floating-point multiplication, addition, subtraction are marked contractable
+!!! danger
+    All kernel launches are asynchronous, each kernel produces an event token that
+    has to be waited upon, before reading or writing memory that was passed as an
+    argument to the kernel. See [dependencies](@ref dependencies) for a full
+    explanation.
 
-## Examples
-### Memory copy
+## Important difference to Julia
 
-The first example simple copies memory from `A` to `B`
+1. Functions inside kernels are forcefully inlined, except when marked with `@noinline`.
+2. Floating-point multiplication, addition, subtraction are marked contractable.
 
+## Important differences to CUDAnative
 
-````@eval
-using Markdown
-Markdown.parse("""
-```julia
-$(read("../../examples/memcopy.jl", String))
-```
-""")
-````
+1. The kernels are automatically bounds-checked against either the dynamic or statically
+   provided `ndrange`.
+2. Functions like `Base.sin` are mapped to `CUDAnative.sin`.
 
 ## How to debug kernels
 
+*TODO*
+
 ## How to profile kernels
+
+*TODO*

docs/src/kernels.md

@@ -1,15 +1,20 @@
-# Kernel language operations
+# Writing kernels 
 
-These kernel language constructs are intendend to be used as part
+These kernel language constructs are intended to be used as part
 of [`@kernel`](@ref) functions and not outside that context.
 
-```@docs
-@shmem
-@scratchpad
-@index
-@synchronize
-```
+## Constant arguments
 
-## Memory kinds
-### Shared memory:
-### Scratch memory
+[`@Const`](@ref)
+
+## Indexing
+
+There are several [`@index`](@ref) variants.
+
+## Local memory, variable lifetime and private memory
+
+[`@localmem`](@ref), [`@synchronize`](@ref), [`@private`](@ref)
+
+# Launching kernels
+
+## [Kernel dependencies](@id dependencies)

examples/memcopy.jl

@@ -7,43 +7,20 @@ using Test
     @inbounds A[I] = B[I]
 end
 
-A = zeros(128, 128)
-B = ones(128, 128)
-
 function mycopy!(A::Array, B::Array)
     @assert size(A) == size(B)
-    kernel = copy_kernel!(ScalarCPU(), 32)
+    kernel = copy_kernel!(CPU(), 8)
     kernel(A, B, ndrange=length(A))
 end
 
 function mycopy_static!(A::Array, B::Array)
     @assert size(A) == size(B)
-    kernel = copy_kernel!(ScalarCPU(), 32, size(A)) # if size(A) varies this will cause recompilation
-    kernel(A, B, ndrange=size(A))
-end
-
-event = mycopy!(A, B)
-wait(event)
-@test A == B
-
-A = zeros(128, 128)
-event = mycopy_static!(A, B)
-wait(event)
-@test A == B
-
-function mycopy!(A::Array, B::Array)
-    @assert size(A) == size(B)
-    kernel = copy_kernel!(ThreadedCPU(), 8)
-    kernel(A, B, ndrange=length(A))
-end
-
-function mycopy_static!(A::Array, B::Array)
-    @assert size(A) == size(B)
-    kernel = copy_kernel!(ThreadedCPU(), 32, size(A)) # if size(A) varies this will cause recompilation
+    kernel = copy_kernel!(CPU(), 32, size(A)) # if size(A) varies this will cause recompilation
     kernel(A, B, ndrange=size(A))
 end
 
 A = zeros(128, 128)
+B = ones(128, 128)
 event = mycopy!(A, B)
 wait(event)
 @test A == B

src/KernelAbstractions.jl

@@ -1,16 +1,23 @@
 module KernelAbstractions
 
 export @kernel
-export @shmem, @scratchpad, @synchronize, @index
-export Device, GPU, CPU, CUDA, ScalarCPU, ThreadedCPU
+export @Const, @localmem, @private, @synchronize, @index
+export Device, GPU, CPU, CUDA 
 
 using StaticArrays
 using Cassette
 using Requires
 
-###
+"""
+   @kernel function f(args) end
+"""
 macro kernel end
 
+"""
+   @Const(A)
+"""
+macro Const end
+
 abstract type Event end
 import Base.wait
 
@@ -21,31 +28,46 @@ function async_copy! end
 
 ###
 # Kernel language
-# - @shmem
-# - @scratchpad
+# - @localmem
+# - @private
 # - @synchronize
 # - @index
 ###
 
 const shmem_id = Ref(0)
-macro shmem(T, dims)
+
+"""
+   @localmem T dims
+"""
+macro localmem(T, dims)
     id = (shmem_id[]+= 1)
 
     quote
         $SharedMemory($(esc(T)), Val($(esc(dims))), Val($id))
     end
 end
 
-macro scratchpad(T, dims)
+"""
+   @private T dims
+"""
+macro private(T, dims)
     quote
         $Scratchpad($(esc(T)), Val($(esc(dims))))
     end
 end
 
+"""
+   @synchronize()
+"""
 macro synchronize()
     @error "@synchronize not captured or used outside @kernel"
 end
 
+"""
+   @index(Global)
+   @index(Local)
+   @index(Global, Cartesian)
+"""
 macro index(locale, args...)
     if !(locale === :Global || locale === :Local)
         error("@index requires as first argument either :Global or :Local")
@@ -85,11 +107,8 @@ function __index_Global_Cartesian end
 
 abstract type Device end
 abstract type GPU <: Device end
-abstract type CPU <: Device end
-
-struct ScalarCPU   <: CPU end
-struct ThreadedCPU <: CPU end
 
+struct CPU <: Device end
 struct CUDA <: GPU end
 # struct AMD <: GPU end
 # struct Intel <: GPU end