Kernel

The kernel object abstracts function calls in a device. There are restrictions in types that can be passed to kernels as arguments.

Aside from memory objects, the following primitives are allowed as kernel arguments:

Primitive Supported Sizes (bits)
int 8, 16, 32, 64
float 32, 64

OCCA supports custom kernel arguments. For more information, check the Custom Kernel Arguments section.

Destructors

void occa::kernel::free ()

Frees

  • The occa::kernel object
  • The kernel built in the device
  • The backend kernel handle
occa::kernel addVectors = device.buildKernel("addVectors.okl",
                                             "addVectors");
...
addVectors.free();
New in version 1.0

Kernel Information

bool occa::kernel::isInitialized ()

Returns true if the kernel has been built by a device and not freed.

occa::kernel addVectors;
std::cout << "Kernel initialized: " << addVectors.isInitialized() << '\n';
addVectors = device.buildKernel("addVectors.okl",
                                "addVectors");
std::cout << "Kernel initialized: " << addVectors.isInitialized() << '\n';
New in version 1.0
occa::device occa::kernel::getDevice ()

Returns the occa::device that built the kernel object. If the kernel has not been built, the returned device.isInitialized() will return false

addVectors = device.buildKernel("addVectors.okl",
                                "addVectors");
...
occa::device kernelDevice = addVectors.getDevice();
New in version 1.0
const std::string& occa::kernel::mode ()

Returns the mode of the device used to build the kernel object. The mode can also be obtained through its properties.

occa::device device("mode: 'Serial'");
addVectors = device.buildKernel("addVectors.okl",
                                "addVectors");
std::cout << "The device mode is: " << addVectors.mode() << '\n';
New in version 1.0
const std::string& occa::kernel::name ()

Creates a occa::device object from occa::properties

addVectors = device.buildKernel("addVectors.okl",
                                "addVectors");
# Will print "addVectors"
std::cout << "Kernel name: " << addVectors.name() << '\n';
New in version 1.0
const std::string& occa::kernel::sourceFilename ()

Creates a occa::device object from occa::properties

addVectors = device.buildKernel("addVectors.okl",
                                "addVectors");
# Will print "addVectors.okl"
std::cout << "Kernel compiled from: " << addVectors.sourceFilename() << '\n';
New in version 1.0
const std::string& occa::kernel::binaryFilename ()

Creates a occa::device object from occa::properties

addVectors = device.buildKernel("addVectors.okl",
                                "addVectors");
# Will print "~/.occa/cache/<hash>/binary"
std::cout << "Kernel compiled from: " << addVectors.binaryFilename() << '\n';
New in version 1.0

Kernel Launch

void occa::kernel::operator ()

Launches the kernel using the passed arguments

Parameters:

  • arg1, [arg2, ...]  -  

    Arguments to the kernel launch. Currently a maximum of 100 total arguments can be sent which includes arguments that expand into more arguments.

addVectors(10, a, b);
New in version 1.0

Manual Kernel Launch

void occa::kernel::setRunDims (
occa::dim outer,
occa::dim inner
)

Sets the for(;;; outer) and for(;;; inner) loop dimensions

Parameters:

  • outer  -  

    Loop dimensions for for(;;; outer) loops

  • inner  -  

    Loop dimensions for for(;;; inner) loops

addVectors.setRunDims(1000, 256);
addVectors.setRunDims(occa::dim(1000, 1000),
                      occa::dim(256, 256));
New in version 1.0
void occa::kernel::addArgument (
const int argPos,
const kernelArg &arg
)

Adds arg as the argPos -th argument

Parameters:

  • argPos  -  

    Index where arg is passed as a kernel argument

  • arg  -  

    Argument that will be passed

addVectors.clearArguments();
addVectors.addArgument(0, 100);
addVectors.addArgument(1, a);
addVectors.addArgument(2, b);
addVectors.addArgument(3, ab);
addVectors.runFromArguments();
New in version 1.0
void occa::kernel::runFromArguments () const

Runs kernel with arguments passed through occa::kernel::addArgument()

addVectors.clearArguments();
addVectors.addArgument(0, 100);
addVectors.addArgument(1, a);
addVectors.addArgument(2, b);
addVectors.addArgument(3, ab);
addVectors.runFromArguments();
New in version 1.0
void occa::kernel::clearArgumentList ()

Clears the kernel argument list. It is mainly used to prevent accidental reuse of arguemnts in future kernel calls.

addVectors.clearArguments();
addVectors.addArgument(0, 100);
addVectors.addArgument(1, a);
addVectors.addArgument(2, b);
addVectors.addArgument(3, ab);
addVectors.runFromArguments();
New in version 1.0

Interoperability

void* occa::device::getHandle (
const occa::properties &props = occa::properties()
)

Returns a handle the occa:kernel uses launch device kernels. The return format is dependent on the backend and props.

Parameters:

  • props  -  

    Additional information that might be needed to get specific handle objects from the backend

New in version 1.0