edu.rit.gpu

Interface Kernel

public interface Kernel

Interface Kernel specifies the base interface for a GPU kernel function. To use a GPU kernel function:

1. Write the C or C++ code for a CUDA module containing one or more kernel functions to be executed on the GPU. The kernel function(s) must be declared to use "C" call syntax; for example:
   extern "C" __global__ void foo (...)
   Compile the CUDA module using the nvcc compiler.

2. For each kernel function in the CUDA module, write a separate Java interface, as follows.
   • The interface name can be whatever you want.
   • The interface must extend interface Kernel.
   • The interface must declare one and only one method.
   • The method's name must be identical to that of the kernel function. Suppose the method's name is foo.
   • The foo method must return void.
   • The foo method's arguments must appear in the same order as those of the kernel function.
   • Declare each foo method argument's data type to correspond with the kernel function argument's data type as listed in the table below. (Kernel function arguments of other types are not supported at this time.)

     Java data type		C data type
     boolean		int
     byte		char, unsigned char
     char		unsigned short int
     short		short int, unsigned short int
     int		int, unsigned int
     long		long long int, unsigned long long int
     float		float
     double		double
     GpuByteArray		char*, unsigned char*
     GpuShortArray		short int*, unsigned short int*
     GpuIntArray		int*, unsigned int*
     GpuLongArray		long long int*, unsigned long long int*
     GpuFloatArray		float*
     GpuDoubleArray		double*
     GpuByteMatrix		char**, unsigned char**
     GpuShortMatrix		short int**, unsigned short int**
     GpuIntMatrix		int**, unsigned int**
     GpuLongMatrix		long long int**, unsigned long long int**
     GpuFloatMatrix		float**
     GpuDoubleMatrix		double**
     GpuStructVbl		struct T*
     GpuStructArray		struct T*
     GpuStructMatrix		struct T**

3. Call the getModule() method on a Gpu object, specifying the name of the compiled CUDA module file relative to the Java class path. This returns a Module object.

4. Suppose the kernel function interface is named Bar. Call the getKernel() method on the Module object, as follows:
   Bar proxy = module.getKernel (Bar.class);
   This returns a reference to a proxy object that implements interface Bar.

5. Configure the kernel by calling the setGridDim(), setBlockDim(), setCacheConfig(), and setDynamicSharedMemorySize() methods on the Bar proxy object as necessary.

6. Set the contents of any input variables (instances of GpuVbl subclasses), and transfer these from host to device.

7. Launch the kernel by calling the foo method on the Bar proxy object, passing in the desired argument values. The foo method returns when the kernel finishes.

8. Transfer any output variables (instances of GpuVbl subclasses) from device to host, and examine their contents.

Study the source code of the classes in package edu.rit.pj2.example to see examples of Parallel Java 2 GPU programs.

Note: A class that implements interface Kernel is not multiple thread safe. It is assumed that only one thread at a time will call methods on a Kernel object.

Method Summary

Methods

Modifier and Type	Method and Description
void	setBlockDim(int blockDimX) Specify that this kernel function will be invoked with a one-dimensional block.
void	setBlockDim(int blockDimX, int blockDimY) Specify that this kernel function will be invoked with a two-dimensional block.
void	setBlockDim(int blockDimX, int blockDimY, int blockDimZ) Specify that this kernel function will be invoked with a three-dimensional block.
void	setCacheConfig(CacheConfig config) Specify that this kernel function will be invoked with the given cache configuration.
void	setDynamicSharedMemorySize(int bytesize) Specify that this kernel function will be invoked with the given dynamic shared memory size.
void	setGridDim(int gridDimX) Specify that this kernel function will be invoked with a one-dimensional grid.
void	setGridDim(int gridDimX, int gridDimY) Specify that this kernel function will be invoked with a two-dimensional grid.
void	setGridDim(int gridDimX, int gridDimY, int gridDimZ) Specify that this kernel function will be invoked with a three-dimensional grid.

Method Detail

setGridDim

void setGridDim(int gridDimX)

Specify that this kernel function will be invoked with a one-dimensional grid. If not specified, the default is a one-dimensional grid with gridDimX = 1.

Parameters:

gridDimX - Grid X dimension (≥ 1).

Throws:

java.lang.IllegalArgumentException - (unchecked exception) Thrown if gridDimX < 1.

See Also:

setGridDim(int,int), setGridDim(int,int,int)

setGridDim

void setGridDim(int gridDimX,
              int gridDimY)

Specify that this kernel function will be invoked with a two-dimensional grid. If not specified, the default is a one-dimensional grid with gridDimX = 1.

Parameters:

gridDimX - Grid X dimension (≥ 1).

gridDimY - Grid Y dimension (≥ 1).

Throws:

java.lang.IllegalArgumentException - (unchecked exception) Thrown if gridDimX < 1 or gridDimY < 1.

See Also:

setGridDim(int), setGridDim(int,int,int)

setGridDim

void setGridDim(int gridDimX,
              int gridDimY,
              int gridDimZ)

Specify that this kernel function will be invoked with a three-dimensional grid. If not specified, the default is a one-dimensional grid with gridDimX = 1.

Parameters:

gridDimX - Grid X dimension (≥ 1).

gridDimY - Grid Y dimension (≥ 1).

gridDimZ - Grid Z dimension (≥ 1).

Throws:

java.lang.IllegalArgumentException - (unchecked exception) Thrown if gridDimX < 1 or gridDimY < 1 or gridDimZ < 1.

See Also:

setGridDim(int), setGridDim(int,int)

setBlockDim

void setBlockDim(int blockDimX)

Specify that this kernel function will be invoked with a one-dimensional block. If not specified, the default is a one-dimensional block with blockDimX = 1.

Parameters:

blockDimX - Block X dimension (≥ 1).

Throws:

java.lang.IllegalArgumentException - (unchecked exception) Thrown if blockDimX < 1.

See Also:

setBlockDim(int,int), setBlockDim(int,int,int)

setBlockDim

void setBlockDim(int blockDimX,
               int blockDimY)

Specify that this kernel function will be invoked with a two-dimensional block. If not specified, the default is a one-dimensional block with blockDimX = 1.

Parameters:

blockDimX - Block X dimension (≥ 1).

blockDimY - Block Y dimension (≥ 1).

Throws:

java.lang.IllegalArgumentException - (unchecked exception) Thrown if blockDimX < 1 or blockDimY < 1.

See Also:

setBlockDim(int), setBlockDim(int,int,int)

setBlockDim

void setBlockDim(int blockDimX,
               int blockDimY,
               int blockDimZ)

Specify that this kernel function will be invoked with a three-dimensional block. If not specified, the default is a one-dimensional block with blockDimX = 1.

Parameters:

blockDimX - Block X dimension (≥ 1).

blockDimY - Block Y dimension (≥ 1).

blockDimZ - Block Z dimension (≥ 1).

Throws:

java.lang.IllegalArgumentException - (unchecked exception) Thrown if blockDimX < 1 or blockDimY < 1 or blockDimZ < 1.

See Also:

setBlockDim(int), setBlockDim(int,int)

setCacheConfig

void setCacheConfig(CacheConfig config)

Specify that this kernel function will be invoked with the given cache configuration. If not specified, the default is to use the GPU's cache configuration setting.

Parameters:

config - Cache configuration.

Throws:

java.lang.NullPointerException - (unchecked exception) Thrown if config is null.

GpuException - (unchecked exception) Thrown if a GPU error occurred.

See Also:

Gpu.setCacheConfig(CacheConfig)

setDynamicSharedMemorySize

void setDynamicSharedMemorySize(int bytesize)

Specify that this kernel function will be invoked with the given dynamic shared memory size. If not specified, the default is 0.

Parameters:

bytesize - Number of dynamic shared memory bytes (≥ 0).

Throws:

java.lang.IllegalArgumentException - (unchecked exception) Thrown if bytesize < 0.