Overhaul docs.

samo-lin · Dec 17, 2019 · 1a45f5b · 1a45f5b
1 parent 0b57872
commit 1a45f5b
Show file tree

Hide file tree

Showing 9 changed files with 215 additions and 317 deletions.
diff --git a/docs/Manifest.toml b/docs/Manifest.toml
@@ -0,0 +1,92 @@
+# This file is machine-generated - editing it directly is not advised
+
+[[Base64]]
+uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+
+[[Dates]]
+deps = ["Printf"]
+uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"
+
+[[Distributed]]
+deps = ["Random", "Serialization", "Sockets"]
+uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
+
+[[DocStringExtensions]]
+deps = ["LibGit2", "Markdown", "Pkg", "Test"]
+git-tree-sha1 = "88bb0edb352b16608036faadcc071adda068582a"
+uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+version = "0.8.1"
+
+[[Documenter]]
+deps = ["Base64", "Dates", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
+git-tree-sha1 = "885467cebde4639a3d81953652cc53ff5a73cb87"
+uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+version = "0.24.3"
+
+[[InteractiveUtils]]
+deps = ["Markdown"]
+uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+
+[[JSON]]
+deps = ["Dates", "Mmap", "Parsers", "Unicode"]
+git-tree-sha1 = "b34d7cef7b337321e97d22242c3c2b91f476748e"
+uuid = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+version = "0.21.0"
+
+[[LibGit2]]
+uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
+
+[[Libdl]]
+uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
+
+[[Logging]]
+uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
+
+[[Markdown]]
+deps = ["Base64"]
+uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
+
+[[Mmap]]
+uuid = "a63ad114-7e13-5084-954f-fe012c677804"
+
+[[Parsers]]
+deps = ["Dates", "Test"]
+git-tree-sha1 = "0139ba59ce9bc680e2925aec5b7db79065d60556"
+uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
+version = "0.3.10"
+
+[[Pkg]]
+deps = ["Dates", "LibGit2", "Libdl", "Logging", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
+uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+
+[[Printf]]
+deps = ["Unicode"]
+uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+
+[[REPL]]
+deps = ["InteractiveUtils", "Markdown", "Sockets"]
+uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+
+[[Random]]
+deps = ["Serialization"]
+uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+
+[[SHA]]
+uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"
+
+[[Serialization]]
+uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+
+[[Sockets]]
+uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
+
+[[Test]]
+deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]
+uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[[UUIDs]]
+deps = ["Random", "SHA"]
+uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+
+[[Unicode]]
+uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,17 +1,28 @@
 using Documenter, CUDAdrv
 
-makedocs(
- modules = [CUDAdrv],
- format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
- sitename = "CUDAdrv.jl",
- pages = [
- "Home" => "index.md",
- "Manual" => [
- "man/usage.md"
- ],
- "Library" => [
- "lib/api.md",
+const src = "https://github.com/JuliaGPU/CUDAdrv.jl"
+const dst = "https://juliagpu.gitlab.io/CUDAdrv.jl/"
+
+function main()
+ makedocs(
+ sitename = "CUDAdrv.jl",
+ authors = "Tim Besard",
+ repo = "$src/blob/{commit}{path}#{line}",
+ format = Documenter.HTML(
+ # Use clean URLs on CI
+ prettyurls = get(ENV, "CI", nothing) == "true",
+ canonical = dst,
+ assets = ["assets/favicon.ico"],
+ analytics = "UA-154489943-5",
+ ),
+ doctest = false,
+ pages = Any[
+ "Home" => "index.md",
+ "APIs" => [
+ "driver.md",
+ ]
  ]
- ],
- doctest = true
-)
+ )
+end
+
+isinteractive() || main()
diff --git a/docs/src/assets/favicon.ico b/docs/src/assets/favicon.ico
diff --git a/docs/src/assets/logo.png b/docs/src/assets/logo.png
diff --git a/docs/src/lib/api.md → docs/src/driver.md b/docs/src/lib/api.md → docs/src/driver.md
@@ -1,4 +1,4 @@
-# API wrappers
+# CUDA driver
 
 This section lists the package's public functionality that directly corresponds to
 functionality of the CUDA driver API. In general, the abstractions stay close to those of
@@ -8,20 +8,6 @@ the CUDA driver API, so for more information on certain library calls you can co
 The documentation is grouped according to the modules of the driver API.
 
 
-## Installation properties
-
-```@docs
-CUDAdrv.vendor
-```
-
-
-## Initialization
-
-```@docs
-CUDAdrv.init
-```
-
-
 ## Error Handling
 
 ```@docs
@@ -63,7 +49,7 @@ CUDAdrv.CuContext
 CUDAdrv.destroy!(::CuContext)
 CUDAdrv.CuCurrentContext
 CUDAdrv.activate(::CuContext)
-CUDAdrv.synchronize(::CuContext)
+CUDAdrv.synchronize()
 CUDAdrv.device(::CuContext)
 ```
 
@@ -96,8 +82,8 @@ CUDAdrv.CuFunction
 ```@docs
 CUDAdrv.CuGlobal
 CUDAdrv.eltype(::CuGlobal)
-CUDAdrv.get(::CuGlobal)
-CUDAdrv.set{T}(::CuGlobal{T}, ::T)
+Base.getindex(::CuGlobal)
+Base.setindex!(::CuGlobal{T}, ::T) where {T}
 ```
 
 ### Linker
@@ -111,27 +97,42 @@ CUDAdrv.complete
 CUDAdrv.CuModule(::CUDAdrv.CuLinkImage, args...)
 ```
 
+
 ## Memory Management
 
+Three kinds of memory buffers can be allocated: device memory, host memory, and unified
+memory. Each of these buffers can be allocated by calling `alloc` with the type of buffer as
+first argument, and freed by calling `free`. Certain buffers have specific methods defined.
+
+```@docs
+CUDAdrv.Mem.DeviceBuffer
+CUDAdrv.Mem.alloc(::Type{Mem.DeviceBuffer}, ::Integer)
+```
+
+```@docs
+CUDAdrv.Mem.HostBuffer
+CUDAdrv.Mem.alloc(::Type{Mem.HostBuffer}, ::Integer, flags)
+CUDAdrv.Mem.register(::Type{Mem.HostBuffer}, ::Ptr, ::Integer, flags)
+CUDAdrv.Mem.unregister(::Mem.HostBuffer)
+```
+
 ```@docs
-CUDAdrv.Mem.alloc
-CUDAdrv.Mem.free
-CUDAdrv.Mem.set!
-CUDAdrv.Mem.upload
-CUDAdrv.Mem.upload!
-CUDAdrv.Mem.download
-CUDAdrv.Mem.download!
-CUDAdrv.Mem.transfer
-CUDAdrv.Mem.transfer!
+CUDAdrv.Mem.UnifiedBuffer
+CUDAdrv.Mem.alloc(::Type{Mem.UnifiedBuffer}, ::Integer, ::CUDAdrv.CUmemAttach_flags)
+CUDAdrv.Mem.prefetch(::Mem.UnifiedBuffer, bytes::Integer; device, stream)
+CUDAdrv.Mem.advise(::Mem.UnifiedBuffer, ::CUDAdrv.CUmem_advise, ::Integer; device)
 ```
 
+To work with these buffers, you need to `convert` them to a `Ptr` or `CuPtr`. Several
+methods then work with these raw pointers:
+
+
+
 ### Memory info
 
 ```@docs
-CUDAdrv.Mem.info
-CUDAdrv.Mem.total
-CUDAdrv.Mem.used
-CUDAdrv.Mem.free()
+CUDAdrv.available_memory
+CUDAdrv.total_memory
 ```
 
 

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,56 +1,10 @@
 # CUDAdrv.jl
 
-*A Julia wrapper for the CUDA driver API.*
-
-This package aims to provide high-level wrappers for the functionality exposed by the CUDA
-driver API, and is meant for users who need high- or low-level access to the CUDA toolkit or
-the underlying hardware.
-
-The package is built upon the [low-level CUDA driver
-API](http:https://docs.nvidia.com/cuda/cuda-driver-api/), but that shouldn't make the Julia
-wrapper any harder to use. That said, it is a work-in-progress and does not offer the same
-functionality or convenience as the more popular
-[CUDArt](https://github.com/JuliaGPU/CUDArt.jl) package, which is built upon the
-[higher-level CUDA runtime API](http:https://docs.nvidia.com/cuda/cuda-runtime-api/).
-
-
-## Installation
-
-Requirements:
-
-* Julia 0.5 or higher (use
- [v0.1.0](https://github.com/JuliaGPU/CUDAdrv.jl/releases/tag/v0.1.0) of this package
- for compatibility with Julia 0.4)
-* NVIDIA driver, providing `libcuda.so` (the full CUDA toolkit is not required)
-* CUDA hardware
-
-At the Julia REPL:
-
-```julia
-Pkg.add("CUDAdrv")
-using CUDAdrv
-
-# optionally
-Pkg.test("CUDAdrv")
-```
-
-Loading CUDAdrv might display error messages, indicating issues with your set-up. These
-messages can be cryptic as they happen too early for decent error handling to be loaded.
-However, please pay close attention to them as they might prevent CUDAdrv.jl from working
-properly! Some common issues:
-
-* unknown error (code 999): this often indicates that your set-up is broken, eg. because you
- didn't load the correct, or any, kernel module. Please verify your set-up, on Linux by
- executing `nvidia-smi` or on other platforms by compiling and running CUDA C code using
- `nvcc`.
-* no device (code 100): CUDA didn't detect your device, because it is not supported by CUDA
- or because you loaded the wrong kernel driver (eg. legacy when you need regular, or
- vice-versa). CUDAdrv.jl cannot work in this case, because CUDA does not allow us to query
- the driver version without a valid device, something we need in order to version the API
- calls.
-* using library stubs (code -1): if any API call returns -1, you're probably using the CUDA
- driver library stubs which return this value for every function call. This is not
- supported by CUDAdrv.jl, and is only intended to be used when compiling C or C++ code to
- be linked with `libcuda.so` at a time when that library isn't available yet. Unless you
- purposefully added the stub libraries to the search path, please run the build script with
- `JULIA_DEBUG=CUDAdrv` and file a bug report.
+Welcome to the API reference documentation of CUDAdrv.jl. This documentation is a work in
+progress. For general usage instructions of CUDAdrv.jl and the rest of the Julia CUDA
+toolchain, please refer to the [CUDA.jl documentation](https://juliagpu.gitlab.io/CUDA.jl/).
+
+Even though this package is built on the [low-level CUDA driver
+API](http:https://docs.nvidia.com/cuda/cuda-driver-api/), that should not scare you: The wrappers
+provided by CUDAdrv.jl are high level, and generally work similar to the higher-level CUDA
+runtime API.