Skip to content

Commit 712ee5e

Browse files
maleadtmaleadt
committed
Update the documentation.
1 parent df1c279 commit 712ee5e

File tree

10 files changed

+192
-161
lines changed

10 files changed

+192
-161
lines changed

‎README.md

Lines changed: 1 addition & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# GPUArrays
22

3-
*Abstract GPU array functionality for Julia's various GPU backends.*
3+
*Reusable GPU array functionality for Julia's various GPU backends.*
44

55
| **Documentation** | **Build Status** |
66
|:-------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------:|
@@ -25,67 +25,3 @@ This package is the counterpart of Julia's `AbstractArray` interface, but for GP
2525
types: It provides functionality and tooling to speed-up development of new GPU array types.
2626
**This package is not intended for end users!** Instead, you should use one of the packages
2727
that builds on GPUArrays.jl, such as [CuArrays](https://github.com/JuliaGPU/CuArrays.jl).
28-
29-
30-
# Functionality
31-
32-
The GPUArrays.jl package essentially provides two abstract array types: `AbstractGPUArray`
33-
for GPU arrays that live on the hose, and `AbstractDeviceArray` for the device-side
34-
counterpart.
35-
36-
## `AbstractGPUArray`
37-
38-
TODO: describe functionality
39-
40-
## `AbstractDeviceArray`
41-
42-
TODO: describe functionality
43-
44-
45-
# Interfaces
46-
47-
To extend the above functionality to a new array type, you should implement the following
48-
interfaces:
49-
50-
TODO
51-
52-
53-
# Test suite
54-
55-
GPUArrays also provides an extensive test suite that covers all of the functionality that
56-
should be available after implementing the required interfaces. This test suite is part of
57-
this package, but for dependency reasons it is not available when importing the package.
58-
Instead, you should include the code from your `runtests.jl` as follows:
59-
60-
```julia
61-
import GPUArrays
62-
gpuarrays = pathof(GPUArrays)
63-
gpuarrays_root = dirname(dirname(gpuarrays))
64-
include(joinpath(gpuarrays_root, "test", "testsuite.jl"))
65-
```
66-
67-
This however implies that the test system will not know about extra dependencies that are
68-
required by the test suite. To remedy this, you should add the following dependencies to
69-
your `Project.toml`:
70-
71-
```
72-
[extras]
73-
FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
74-
FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
75-
ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
76-
...
77-
78-
[targets]
79-
test = [..., "FFTW", "ForwardDiff", "FillArrays"]
80-
```
81-
82-
83-
# `JLArray`
84-
85-
The `JLArray` type is a reference implementation of the GPUArray interfaces. It does not run
86-
on the GPU, but rather uses Julia's async constructs as its backend. It is constructed as
87-
follows:
88-
89-
```julia
90-
gA = JLArray(A)
91-
```

‎docs/Manifest.toml

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# This file is machine-generated - editing it directly is not advised
2+
3+
[[Base64]]
4+
uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
5+
6+
[[Dates]]
7+
deps = ["Printf"]
8+
uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"
9+
10+
[[Distributed]]
11+
deps = ["Random", "Serialization", "Sockets"]
12+
uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
13+
14+
[[DocStringExtensions]]
15+
deps = ["LibGit2", "Markdown", "Pkg", "Test"]
16+
git-tree-sha1 = "88bb0edb352b16608036faadcc071adda068582a"
17+
uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
18+
version = "0.8.1"
19+
20+
[[Documenter]]
21+
deps = ["Base64", "Dates", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
22+
git-tree-sha1 = "51f0c7df46abb9c07d80e529718951e634670afb"
23+
uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
24+
version = "0.24.4"
25+
26+
[[InteractiveUtils]]
27+
deps = ["Markdown"]
28+
uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
29+
30+
[[JSON]]
31+
deps = ["Dates", "Mmap", "Parsers", "Unicode"]
32+
git-tree-sha1 = "b34d7cef7b337321e97d22242c3c2b91f476748e"
33+
uuid = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
34+
version = "0.21.0"
35+
36+
[[LibGit2]]
37+
uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
38+
39+
[[Libdl]]
40+
uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
41+
42+
[[Logging]]
43+
uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
44+
45+
[[Markdown]]
46+
deps = ["Base64"]
47+
uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
48+
49+
[[Mmap]]
50+
uuid = "a63ad114-7e13-5084-954f-fe012c677804"
51+
52+
[[Parsers]]
53+
deps = ["Dates", "Test"]
54+
git-tree-sha1 = "0139ba59ce9bc680e2925aec5b7db79065d60556"
55+
uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
56+
version = "0.3.10"
57+
58+
[[Pkg]]
59+
deps = ["Dates", "LibGit2", "Libdl", "Logging", "Markdown", "Printf", "REPL", "Random", "SHA", "Test", "UUIDs"]
60+
uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
61+
62+
[[Printf]]
63+
deps = ["Unicode"]
64+
uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"
65+
66+
[[REPL]]
67+
deps = ["InteractiveUtils", "Markdown", "Sockets"]
68+
uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
69+
70+
[[Random]]
71+
deps = ["Serialization"]
72+
uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
73+
74+
[[SHA]]
75+
uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"
76+
77+
[[Serialization]]
78+
uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
79+
80+
[[Sockets]]
81+
uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
82+
83+
[[Test]]
84+
deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]
85+
uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
86+
87+
[[UUIDs]]
88+
deps = ["Random", "SHA"]
89+
uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
90+
91+
[[Unicode]]
92+
uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"

‎docs/make.jl

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,25 @@ using Documenter, GPUArrays
22

33
makedocs(
44
modules = [GPUArrays],
5-
format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
5+
format = Documenter.HTML(
6+
# Use clean URLs on CI
7+
prettyurls = get(ENV, "CI", nothing) == "true",
8+
assets = ["assets/favicon.ico"],
9+
analytics = "UA-154489943-6",
10+
),
611
sitename = "GPUArrays.jl",
712
pages = [
8-
"Home" => "index.md",
13+
"Home" => "index.md",
14+
"Interface" => "interface.md",
15+
"Functionality" => [
16+
"functionality/host.md",
17+
"functionality/device.md",
18+
],
19+
"Test suite" => "testsuite.md",
920
],
10-
doctest = true
21+
doctest = true,
1122
)
1223

1324
deploydocs(
14-
repo = "github.com/JuliaGPU/GPUArrays.jl.git"
25+
repo = "github.com/JuliaGPU/GPUArrays.jl.git"
1526
)

‎docs/src/assets/favicon.ico

15 KB
Binary file not shown.

‎docs/src/assets/logo.png

74.1 KB
Loading

‎docs/src/functionality/device.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# `AbstractDeviceArray`
2+
3+
TODO: describe functionality

‎docs/src/functionality/host.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# `AbstractGPUArray`
2+
3+
TODO: describe functionality

‎docs/src/index.md

Lines changed: 20 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,20 @@
1-
# GPUArrays Documentation
2-
3-
GPUArrays is an abstract interface for GPU computations.
4-
Think of it as the AbstractArray interface in Julia Base but for GPUs.
5-
It allows you to write generic julia code for all GPU platforms and implements common algorithms for the GPU.
6-
Like Julia Base, this includes BLAS wrapper, FFTs, maps, broadcasts and mapreduces.
7-
So when you inherit from GPUArrays and overload the interface correctly, you will get a lot
8-
of functionality for free.
9-
This will allow to have multiple GPUArray implementation for different purposes, while
10-
maximizing the ability to share code.
11-
Currently there are two packages implementing the interface namely [CLArrays](https://github.com/JuliaGPU/CLArrays.jl) and [CuArrays](https://github.com/JuliaGPU/CuArrays.jl).
12-
As the name suggests, the first implements the interface using OpenCL and the latter uses CUDA.
13-
14-
15-
16-
# The Abstract GPU interface
17-
18-
Different GPU computation frameworks like CUDA and OpenCL, have different
19-
names for accessing the same hardware functionality.
20-
E.g. how to launch a GPU Kernel, how to get the thread index and so forth.
21-
GPUArrays offers a unified abstract interface for these functions.
22-
This makes it possible to write generic code that can be run on all hardware.
23-
GPUArrays itself even contains a pure [Julia implementation](https://github.com/JuliaGPU/GPUArrays.jl/blob/master/src/jlbackend.jl) of this interface.
24-
The julia reference implementation is a great way to debug your GPU code, since it
25-
offers more informative errors and debugging information compared to the GPU backends - which
26-
mostly silently error or give cryptic errors (so far).
27-
28-
You can use the reference implementation by using the `GPUArrays.JLArray` type.
29-
30-
The functions that are currently part of the interface:
31-
32-
The low level dim + idx function, with a similar naming scheme as in CUDA:
33-
```Julia
34-
# with * being either of x, y or z
35-
blockidx_*(state), blockdim_*(state), threadidx_*(state), griddim_*(state)
36-
# Known in OpenCL as:
37-
get_group_id, get_local_size, get_local_id, get_num_groups
38-
```
39-
40-
Higher level functionality:
41-
42-
```@docs
43-
gpu_call(f, A::GPUArray, args::Tuple, configuration = length(A))
44-
45-
linear_index(state)
46-
47-
global_size(state)
48-
49-
@linearidx(A, statesym = :state)
50-
51-
@cartesianidx(A, statesym = :state)
52-
53-
synchronize_threads(state)
54-
55-
device(A::AbstractArray)
56-
57-
synchronize(A::AbstractArray)
58-
59-
@LocalMemory(state, T, N)
60-
```
61-
62-
63-
# The abstract TestSuite
64-
65-
Since all array packages inheriting from GPUArrays need to offer the same functionality
66-
and interface, it makes sense to test them in the same way.
67-
This is why GPUArrays contains a test suite which can be called with the array type
68-
you want to test.
69-
70-
You can run the test suite like this:
71-
72-
```Julia
73-
using GPUArrays, GPUArrays.TestSuite
74-
TestSuite.run_tests(MyGPUArrayType)
75-
```
76-
If you don't want to run the whole suite, you can also run parts of it:
77-
78-
79-
```Julia
80-
Typ = JLArray
81-
GPUArrays.allowslow(false) # fail tests when slow indexing path into Array type is used.
82-
83-
TestSuite.run_gpuinterface(Typ) # interface functions like gpu_call, threadidx, etc
84-
TestSuite.run_base(Typ) # basic functionality like launching a kernel on the GPU and Base operations
85-
TestSuite.run_blas(Typ) # tests the blas interface
86-
TestSuite.run_broadcasting(Typ) # tests the broadcasting implementation
87-
TestSuite.run_construction(Typ) # tests all kinds of different ways of constructing the array
88-
TestSuite.run_fft(Typ) # fft tests
89-
TestSuite.run_linalg(Typ) # linalg function tests
90-
TestSuite.run_mapreduce(Typ) # mapreduce sum, etc
91-
TestSuite.run_indexing(Typ) # indexing tests
92-
```
1+
# GPUArrays.jl
2+
3+
GPUArrays is a package that provides reusable GPU array functionality for Julia's various
4+
GPU backends. Think of it as the `AbstractArray` interface from Base, but for GPU array
5+
types. It allows you to write generic julia code for all GPU platforms and implements common
6+
algorithms for the GPU. Like Julia Base, this includes BLAS wrapper, FFTs, maps, broadcasts
7+
and mapreduces. So when you inherit from GPUArrays and overload the interface correctly, you
8+
will get a lot of functionality for free. This will allow to have multiple GPUArray
9+
implementation for different purposes, while maximizing the ability to share code.
10+
11+
**This package is not intended for end users!** Instead, you should use one of the packages
12+
that builds on GPUArrays.jl. There is currently only a single package that actively builds
13+
on these interfaces, namely [CuArrays.jl](https://github.com/JuliaGPU/CuArrays.jl).
14+
15+
In this documentation, you will find more information on the interface that you are expected
16+
to implement, the functionality you gain by doing so, and the test suite that is available
17+
to verify your implementation. GPUArrays.jl also provides a reference implementation of
18+
these interfaces on the CPU: The `JLArray` array type uses Julia's parallel programming
19+
functionality to simulate GPU execution, and will be used throughout this documentation to
20+
illustrate functionality.

‎docs/src/interface.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Interface
2+
3+
To extend the above functionality to a new array type, you should implement the following
4+
interfaces:
5+
6+
TODO

‎docs/src/testsuite.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Test suite
2+
3+
GPUArrays provides an extensive test suite that covers all of the functionality that should
4+
be available after implementing the required interfaces. This test suite is part of this
5+
package, but for dependency reasons it is not available when importing the package. Instead,
6+
you should include the code from your `runtests.jl` as follows:
7+
8+
```julia
9+
import GPUArrays
10+
gpuarrays = pathof(GPUArrays)
11+
gpuarrays_root = dirname(dirname(gpuarrays))
12+
include(joinpath(gpuarrays_root, "test", "testsuite.jl"))
13+
```
14+
15+
This however implies that the test system will not know about extra dependencies that are
16+
required by the test suite. To remedy this, you should add the following dependencies to
17+
your `Project.toml`:
18+
19+
```
20+
[extras]
21+
FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
22+
FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
23+
ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
24+
...
25+
26+
[targets]
27+
test = [..., "FFTW", "ForwardDiff", "FillArrays"]
28+
```
29+
30+
With this set-up, you can run the test suite like this:
31+
32+
```julia
33+
using GPUArrays, GPUArrays.TestSuite
34+
TestSuite.run_tests(MyGPUArrayType)
35+
```
36+
If you don't want to run the whole suite, you can also run parts of it:
37+
38+
39+
```julia
40+
T = JLArray
41+
GPUArrays.allowscalar(false) # fail tests when slow indexing path into Array type is used.
42+
43+
TestSuite.run_gpuinterface(T) # interface functions like gpu_call, threadidx, etc
44+
TestSuite.run_base(T) # basic functionality like launching a kernel on the GPU and Base operations
45+
TestSuite.run_blas(T) # tests the blas interface
46+
TestSuite.run_broadcasting(T) # tests the broadcasting implementation
47+
TestSuite.run_construction(T) # tests all kinds of different ways of constructing the array
48+
TestSuite.run_fft(T) # fft tests
49+
TestSuite.run_linalg(T) # linalg function tests
50+
TestSuite.run_mapreduce(T) # mapreduce sum, etc
51+
TestSuite.run_indexing(T) # indexing tests
52+
```

0 commit comments

Comments
 (0)