.github/workflows/documentation.yml

@@ -0,0 +1,26 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1.9'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

README.md

@@ -1,10 +1,13 @@
-# Jai: Julia Accelerator Interfaces
+# Jai: Julia accelerator interfaces
 
-[![Build Status](https://github.com/grnydawn/AccelInterfaces.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/grnydawn/AccelInterfaces.jl/actions/workflows/CI.yml?query=branch%3Amain)
+[![Build Status](https://github.com/grnydawn/AccelInterfaces.jl/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/grnydawn/AccelInterfaces.jl/actions/workflows/CI.yml?query=branch%3Amaster)
+[![documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://grnydawn.github.io/AccelInterfaces.jl/)
 
-**Jai** is a GPU and CPU programming interface for [Julia](http://julialang.org/) programmers.
+**Jai** is an accelerator programming interfaces for [Julia](http://julialang.org/) programmers.
 
-**Jai** focuses on reusing Fortran and C/C++ codes, especially for large-scale simulation applications. Jai does not limit its support to specific languages or programming frameworks, as long as the code can be compiled as a shared library. In practice, **Jai** currently supports Fortran, C/C++, Fortran OpenMP, Fortran OpenACC, C++ OpenMP, CUDA, and HIP.
+**Jai** focuses on reusing Fortran and C/C++ codes, especially for large-scale simulation applications, within Julia. Jai does not limit its support to specific languages or programming frameworks, as long as the code can be compiled as a shared library. Currently, Jai supports the basic capabilities of Fortran, C/C++, Fortran OpenMP, Fortran OpenACC, C++ OpenMP, CUDA, as well as HIP.
+
+This package is still in the early stages of development. Please use this package at your own risk.
 
 ## Package features
 
@@ -20,6 +23,9 @@
 Pkg.add("AccelInterfaces")
 ```
 
+## Manual
+This README is a quick introduction in using AccelInterfaces.jl (Jai). For more details you can read the latest [documentation](https://grnydawn.github.io/AccelInterfaces.jl/).
+
 ## Quickstart
 
 The following Julia code calculates a vector sum, whose main algorithm is written in Fortran.
@@ -38,6 +44,12 @@ kernel_text = """
     !\$acc end parallel loop
 """
 
+    const N = 10
+    x = fill(1, N)
+    y = fill(2, N)
+    z = fill(0, N)
+    answer = fill(3, N)
+
     @jaccel
 
     @jkernel kernel_text mykernel1 framework(fortran="gfortran -fPIC -shared")
@@ -90,7 +102,7 @@ NOTE: To run the Fortran OpenACC case, copy the following code lines at the end
 The Fortran OpenACC code shares most of the code with the above Fortran example, with the exception of additional lines for OpenACC annotations. To use fortran_openacc, the user can simply add the name fortran_openacc to the header of the kernel string, as shown in the "kernel_text" variable in the example.
 
 #### Creates a Jai kernel context
-To compile the example code for Fortran OpenACC, the framework clause in the @jaccel macro must contain the compile string for OpenACC arrays.
+To compile the example code for Fortran OpenACC, the framework clause in the @jkernel macro must contain the compile string for OpenACC arrays.
 
 #### Allocate GPU memory and copy data from Julia Arrays to GPU memory
 The @jenterdata directive is used to allocate GPU memory and copy data from CPU to GPU. Once the user adds Julia variable names, Jai uses the data movement API according to the framework used, OpenACC in this case.

docs/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -1,4 +1,7 @@
 using Documenter
+
+push!(LOAD_PATH,"../src/")
+
 using AccelInterfaces
 
 makedocs(
@@ -10,6 +13,6 @@ makedocs(
 # Documenter can also automatically deploy documentation to gh-pages.
 # See "Hosting Documentation" and deploydocs() in the Documenter manual
 # for more information.
-#=deploydocs(
-    repo = "<repository url>"
-)=#
+deploydocs(
+    repo = "https://github.com/grnydawn/AccelInterfaces.jl"
+)

docs/src/index.md

@@ -1,24 +1,25 @@
-# Julia Accelerator Interfaces(Jai)
+# Julia AccelInterfaces.jl (**Jai**)
 
-Jai is a GPU and CPU programming interface for Julia programmers.
+*Accelerator programming interfaces for Julia programmers*
 
-Jai focuses on reusing Fortran and C/C++ codes. The Fortran and C/C++ codes could include directive based GPU programming such as OpenAcc and OpenMP Target. Or even the codes are written in CUDA or HIP.
+A package for reusing Fortran/C/C++ codes of large-scale simulations in Julia.
 
-# AccelInterfaces.jl
+## Package Features
 
-```@docs
-AccelInterfaces
-```
+- Provides Julia users with an OpenMP-like macro interface to run CPU and GPU code.
+- Automatically generates a shared library of pre-existing Fortran/C/C++ code so that it can be called from Julia.
+- Provides a simple interface to exchange data between Julia Arrays and GPU memory.
+- Allows different CPU and GPU programming frameworks to coexist within an application.
+- Boosts the performance of original code through just-in-time compilation.
 
-## Module Index
+!!! warning
 
-```@index
-Modules = [AccelInterfaces]
-Order   = [:constant, :type, :function, :macro]
-```
-## Detailed API
+    This package is in the early stages of development. Please use it at your own risk.
 
-```@autodocs
-Modules = [AccelInterfaces]
-Order   = [:constant, :type, :function, :macro]
-```
+The [Getting-Started](@ref) provides a tutorial explaining how to get started using AccelInterfaces.
+
+The [Examples](@ref) shows a Jai example for OpenACC.
+
+[jlweather demo](@ref) is a Julia port of [miniWeather](https://github.com/mrnorman/miniWeather) using [Jai](https://github.com/grnydawn/AccelInterfaces.jl).
+
+See [Jai API](@ref) for the explations of Jai macros.

docs/src/man/api.md

@@ -0,0 +1,21 @@
+
+# Jai API
+
+Using Jai API, Julia user can easily run CPU or GPU codes written in Fortran/C/C++.
+
+
+# list of Jai API
+
+Jai API is consist of serveral Julia macros.
+
+```@index
+Modules = [AccelInterfaces]
+Order   = [:constant, :type, :function, :macro]
+```
+
+# Detailed API
+
+```@autodocs
+Modules = [AccelInterfaces]
+Order   = [:constant, :type, :function, :macro]
+```

docs/src/man/examples.md

@@ -0,0 +1,87 @@
+# Examples
+
+## Simple OpenAcc example
+
+### Preparing an OpenACC code
+
+User can specify the function body code using Julia string that contains the code, or a Julia string that points to Jai Kernel File(.knl) in simple text format. The following Julia code calculates a vector sum, whose main algorithm is written in Fortran OpenACC.
+
+```julia
+# main.jl
+
+using AccelInterfaces
+
+kernel_text = """
+[fortran_openacc]
+    INTEGER i
+
+    !\$acc parallel loop 
+    DO i=LBOUND(x, 1), UBOUND(x, 1)
+        z(i) = x(i) + y(i)
+    END DO
+    !\$acc end parallel loop
+"""
+```
+
+The "kernel\_text" string contains a Fortran DO loop that actually calculates the vector sum. OpenACC annotations surround the DO loop, and the header at the top of the string specifies that the code contains both of Fortran OpenACC code.
+
+### Annotating Julia main code with Jai macros
+
+Once "embedded" code is ready as explained in previous section, we need to use Jai macros to drive the execution of the embedded code.
+
+```julia
+    # continued from previous Julia code
+
+    const N = 10
+    x = fill(1, N)
+    y = fill(2, N)
+    z = fill(0, N)
+    answer = fill(3, N)
+
+    @jkernel kernel_text mykernel framework(fortran_openacc="ftn -h acc,noomp -fPIC -shared")
+
+    @jenterdata alloc(x, y, z) updateto(x, y)
+
+    @jlaunch mykerne input(x, y)  output(z)
+
+    @jexitdata updatefrom(z) delete(x, y, z)
+
+    @jdecel
+
+    @assert z == answer
+```
+
+#### Creates a Jai accelerator context
+The @jaccel directive creates a Jai accelerator context.
+
+#### Creates a Jai kernel context
+The @jkernel directive creates a Jai kernel context. As a first caluse of @jkernel, users should specify the Jai Kernel through a Julia string as in this example. Alternatively, the user can provide Jai with a path string to a text file that contains the kernel. To identify the kernel context, we use the literal name mykernel.
+
+The framework clause specifies the kind of acceleration, which in this example is Fortran OpenACC. The user can provide Jai with the actual compiler command line to generate a shared library. The command line should include the compiler and all compiler flags, except the -o flag, which specifies the name of the output file and the path to the input source file.
+
+#### Allocate GPU memory and copy data from Julia Arrays to GPU memory
+The @jenterdata directive is used to allocate GPU memory and copy data from CPU to GPU. Once the user adds Julia variable names, Jai uses the data movement API according to the framework used, OpenACC in this case.
+
+#### Launches a kernel
+The first argument to the @jlaunch directive is the name of the kernel context used in the @jkernel directive. The user then adds the names of variables to the input and output clauses accordingly. However, it is important to note that you should only use simple variable names for inputs and outputs to/from the kernel in the @jlaunch directive. For example, you cannot write something like this:
+```julia
+@jlaunch mykernel input(x+1, func(y)) output(z::Vector) # Jai Syntax Error
+```
+#### Copy data from GPU memory to Julia Arrays and deallocate GPU memory
+The @jexitdata directive is used to deallocate GPU memory and copy data from GPU to CPU. Once the user adds Julia variable names, Jai uses the data movement API according to the framework used, OpenACC in this case.
+
+#### Remove a Jai accelerator context
+Lastly, "@jdecel" is used to declare the end of the Jai accelerator context.
+
+### Running the Julia main code
+
+Run the Julia main. During the first run, Jai will genrate a shared library and load the shared library and finally make a call to the function in the shared library. This process is done automatically and takes some time at the first run. Howver, once the process is finished with success, the generated shared library is cached and will be loaded immediately unless there is no change.
+
+```bash
+> julia main.jl
+```
+
+## Further readings
+
+[jlweather](@ref) : Jai implementations of [miniWeather](https://github.com/mrnorman/miniWeather)
+

docs/src/man/guide.md

@@ -0,0 +1,88 @@
+# Getting-Started
+
+AccelInterfaces.jl(**Jai**) focuses on reusing Fortran and C/C++ codes, especially for large-scale simulation applications, within Julia. **Jai** does not limit its support to specific languages or programming frameworks, as long as the code can be compiled as a shared library. Currently, **Jai** supports the basic capabilities of Fortran, C/C++, Fortran OpenMP, Fortran OpenACC, C++ OpenMP, CUDA, as well as HIP.
+
+## Installation
+
+**Jai** can be installed using the Julia package manager.
+From the Julia REPL, run
+
+```
+pkg> add AccelInterfaces
+```
+
+## Preparing a Fortran/C/C++ code to be called from Julia
+
+First, we need to prepare a Fortran/C/C++("embedded") code that will be called from Julia main. The embedded code is the body part of Fortran/C/C++ function without a function signature and a functon end marker(such as "end function" in Fortran and "}"in C/C++). Jai will use the embedded code to generate a shared library after adding proper function signature based on input variables in Julia.
+
+User can specify the function body code using Julia string that contains the code, or a Julia string that points to Jai Kernel File(.knl) in simple text format. The following Julia code calculates a vector sum, whose main algorithm is written in Fortran.
+
+```julia
+# main.jl
+
+using AccelInterfaces
+
+kernel_text = """
+[fortran]
+    INTEGER i
+
+    DO i=LBOUND(x, 1), UBOUND(x, 1)
+        z(i) = x(i) + y(i)
+    END DO
+"""
+```
+
+The "kernel\_text" string contains a Fortran DO loop that actually calculates the vector sum. The header at the top of the string specifies that the code contains both of Fortran code.
+
+## Annotating Julia main code with Jai macros
+
+Once "embedded" code is ready as explained in previous section, we need to use Jai macros to drive the execution of the embedded code.
+
+```julia
+    # continued from previous Julia code
+
+    const N = 10
+    x = fill(1, N)
+    y = fill(2, N)
+    z = fill(0, N)
+    answer = fill(3, N)
+
+    @jaccel
+
+    @jkernel kernel_text mykernel framework(fortran="gfortran -fPIC -shared")
+
+    @jlaunch mykernel input(x, y)  output(z)
+
+    @jdecel
+
+    @assert z == answer
+```
+
+#### Creates a Jai accelerator context
+The @jaccel directive creates a Jai accelerator context.
+
+#### Creates a Jai kernel context
+The @jkernel directive creates a Jai kernel context. The user must specify the string of the kernel, as in this example. Alternatively, the user can provide Jai with a path string to a text file that contains the kernel. To identify the kernel context, we use the literal name mykernel.
+
+The framework clause specifies the kind of acceleration, which in this example is Fortran. The user can provide Jai with the actual compiler command line to generate a shared library. The command line should include the compiler and all compiler flags, except the -o flag, which specifies the name of the output file and the path to the input source file.
+
+#### Launches a kernel
+The first argument to the @jlaunch directive is the name of the kernel context used in the @jkernel directive. The user then adds the names of variables to the input and output clauses accordingly. However, it is important to note that you should only use simple variable names for inputs and outputs to/from the kernel in the @jlaunch directive. For example, you cannot write something like this:
+```julia
+@jlaunch mykernel input(x+1, func(y)) output(z::Vector) # Jai Syntax Error
+```
+
+#### Remove a Jai accelerator context
+Lastly, "@jdecel" is used to declare the end of the Jai accelerator context.
+
+# Running the Julia main code
+
+Run the Julia main. During the first run, Jai will genrate a shared library and load the shared library and finally make a call to the function in the shared library. This process is done automatically and takes some time at the first run. Howver, once the process is finished with success, the generated shared library is cached and will be loaded immediately unless there is no change.
+
+```bash
+> julia main.jl
+```
+
+## Further readings
+
+[Examples](@ref) : Jai examples including using GPU

docs/src/man/jlweather.md

@@ -0,0 +1,5 @@
+# jlweather demo
+
+[jlweather](https://github.com/grnydawn/jlweather) is a Julia port of [miniWeather](https://github.com/mrnorman/miniWeather) using [Jai](https://github.com/grnydawn/AccelInterfaces.jl).
+
+Please see [jlweather](https://github.com/grnydawn/jlweather) for the details of the porting.

src/AccelInterfaces.jl

@@ -2,7 +2,7 @@
 
 
 """
-Julia Accelerator Interfaces(Jai) module
+Julia Accelerator Interfaces (Jai) is a Julia package to reuse large-scale simulations written in Fortran/C/C++.
 """
 module AccelInterfaces
 
@@ -15,7 +15,8 @@ include("kernel.jl")
 include("main.jl")
 include("api.jl")
 
-export @jconfig, @jaccel, @jenterdata, @jkernel, @jlaunch, @jexitdata, @jwait, @jdecel, @jdiff
+export @jaccel, @jenterdata, @jkernel, @jlaunch, @jexitdata, @jwait, @jdecel
+#export @jconfig, @jaccel, @jenterdata, @jkernel, @jlaunch, @jexitdata, @jwait, @jdecel, @jdiff
 
 function _finalize()
 end