User API

Data Types

group nomp_user_types

Below is a list of data types that are used in the user API.

Enums

enum nomp_arg_type_t

Defines argument types supported for a nomp kernel. Used in nomp_jit() which is used for kernel creation. Currently, only integer, float or pointer types are supported as kernel arguments.

Values:

enumerator NOMP_INT: Signed integer argument type.

enumerator NOMP_UINT: Unsigned integer argument type.

enumerator NOMP_FLOAT: Floating point argument type.

enumerator NOMP_PTR: Pointer argument type.

enum nomp_map_direction_t

Defines the update method (operation) in nomp_update().

Values:

enumerator NOMP_ALLOC: Allocate memory on the device.

enumerator NOMP_TO: Copy host data to device. Memory will be allocated if not allocated.

enumerator NOMP_FROM: Copy device data to host.

enumerator NOMP_FREE: Free memory allocated on the device.

enum nomp_arg_properties_t

Defines various argument properties.

Values:

enumerator NOMP_JIT: Argument value is fixed when the kernel is generated.

Functions

group nomp_user_api

libnomp user API functions.

Functions

char *nomp_get_err_str(unsigned id)

Return the log given the log id.

Returns the log of the given error id. Returns NULL if the id is invalid.

Parameters: id – [in] id of the error log returned by nomp_log().
Returns: char*

int nomp_get_err_no(unsigned id)

Return log number given the log id.

Returns the error number given the id. If id is invalid return NOMP_USER_LOG_ID_IS_INVALID. Error number is one of Error codes returned to the user.

Parameters: id – [in] id of the log returned by nomp_log().
Returns: int

int nomp_init(int argc, const char **argv)

Initializes libnomp with the specified backend, platform, device, etc.

Initializes nomp code generation for the specified backend (e.g., OpenCL, CUDA, etc) using command line arguments. Have a look at the accepted arguments below for all available options. If no arguments are specified, default values configured at build time are used for all configurations except for backend and the install directory. The backend name and the install directory are mandatory arguments.

This function Returns a non-zero value if an error occurs during the initialization, otherwise returns 0. Errors can be queried using nomp_get_err_no() and nomp_get_err_str(). Calling this method multiple times (without nomp_finalize in between) will return an error (but not segfault).

Accepted arguments:

--nomp-install-dir <install-dir> Specify libnomp install directory.
--nomp-backend <backend-name> Specify backend name.
--nomp-platform <platform-index> Specify platform id.
--nomp-device <device-index> Specify device id.
--nomp-verbose <verbose-level> Specify verbose level.
--nomp-profile <profile-level> Specify profile level.
--nomp-scripts-dir <scripts-dir> Specify the directory containing
--nomp-annotations-script <annotations-script> Specify the name of the annotations script.

Example usage:

const char *argv[] = {"--nomp-backend", "opencl", "--nomp-device", "0",
"--nomp-platform", "0"};
int argc = 6;
int err = nomp_init(argc, argv);

Parameters

argc – [in] The number of arguments to nomp_init().
argv – [in] Arguments as strings, values followed by options.

Returns

int

int nomp_update(void *ptr, size_t idx0, size_t idx1, size_t unit_size, nomp_map_direction_t op)

libnomp function for managing device memory. This can be used to performs device to host (D2H) and host to device (H2D) memory transfers, device memory allocation and release.

Operation op will be performed on the array slice [start_index, end_index), i.e., on array elements start_index, … end_index - 1. This method returns a non-zero value if there is an error and 0 otherwise.

Example usage:

int N = 10;
double a[10];
for (unsigned i = 0; i < N; i++)
  a[i] = i;

// Copy the value of `a` into device
int err = nomp_update(a, 0, N, sizeof(double), NOMP_TO);

// Execution of a kernel which uses `a`
...

// Copy the updated value of `a` from device
int err = nomp_update(a, 0, N, sizeof(double), NOMP_FROM);

// Free the device memory allocated for `a`
int err = nomp_update(a, 0, N, sizeof(double), NOMP_FREE);

Parameters

ptr – [in] Pointer to host memory location (start of host memory array).
idx0 – [in] Start index in the ptr to start copying.
idx1 – [in] End index in the ptr to end the copying.
unit_size – [in] Size of a single element in the array ptr.
op – [in] Operation to perform (One of nomp_map_direction_t).

Returns

int

int nomp_jit(int *id, const char *csrc, const char **clauses, int nargs, ...)

Generate and compile a kernel for the target backend (OpenCL, etc.) from C source.

Target backend is the one provided during the initialization of libnomp using nomp_init(). User defined code transformations will be applied based on the clauses specified in clauses argument. Additional kernel meta data can be passed using the clauses as well. After clauses, number of arguments to the kernel must be provided. Then for each argument, three values has to be passed. First is the argument name as a string. Second is is the sizeof argument and the third if argument type (one of User types).

Example usage:

int N = 10;
double a[10], b[10];
for (unsigned i = 0; i < N; i++) {
  a[i] = i;
  b[i] = 10 -i
}
const char *knl = "for (unsigned i = 0; i < N; i++) a[i] += b[i];"
static int id = -1;
const char *clauses[4] = {"transform", "file", "function", 0};
int err = nomp_jit(&id, knl, clauses, 3, "a", sizeof(a[0]), NOMP_PTR, "b",
  sizeof(b[0]), NOMP_PTR, "N", sizeof(int), NOMP_INT);

Parameters

id – [out] Id of the generated kernel.
csrc – [in] Kernel source in C.
clauses – [in] Clauses to provide meta information about the kernel.
nargs – [in] Number of arguments to the kernel.
... – [in] Three values for each argument: identifier, sizeof(argument) and argument type.

Returns

int

int nomp_run(int id, ...)

Runs the kernel generated by nomp_jit().

Runs the kernel with a given kernel id. Kernel id is followed by the arguments (i.e., pointers and pointer to scalar variables).

Example usage:

int N = 10;
double a[10], b[10];
for (unsigned i = 0; i < N; i++) {
  a[i] = i;
  b[i] = 10 -i
}

static int id = -1;
const char *knl = "for (unsigned i = 0; i < N; i++) a[i] += b[i];"
const char *clauses[4] = {"transform", "file", "function", 0};
int err = nomp_jit(&id, knl, clauses, 3, "a", sizeof(a[0]), NOMP_PTR, "b",
  sizeof(b[0]), NOMP_PTR, "N", sizeof(int), NOMP_INT);
err = nomp_run(id, a, b, &N);

Parameters

id – [in] Id of the kernel to be run.
... – [in] Arguments to the kernel.

Returns

int

int nomp_sync(void)

Synchronize task execution on device.

Implement a host-side barrier till the device finish executing all the previous nomp kernels and/or memory copies.

Returns: int

int nomp_finalize(void)

Finalizes libnomp runtime including the Python interpreter.

Frees allocated runtime resources for libnomp. Returns a non-zero value if an error occurs during the finalize process, otherwise returns 0. Calling this method before nomp_init() will return an error. Calling this method twice will also return an error.

Returns: int

int nomp_finalize_excluding_interpreter(void)

Finalizes libnomp runtime without finalizing the Python interpreter.

Acts the same as nomp_finalize() except that this method does not finalize the Python interpreter. This method is useful when libnomp has to be re-initialized multiple times in the same process.

Returns: int

Error Codes

group nomp_error_codes

Error codes used by internal libnomp functions when calling nomp_log() with NOMP_ERROR. User can query these error codes using nomp_get_err_no() by passing the return value of a libnomp function call in case of an error. NOMP_SUCCESS is used for error code when nomp_log() is called with NOMP_WARNING or NOMP_INFO.

Defines

NOMP_SUCCESS: libnomp API call was successful.

NOMP_USER_INPUT_IS_INVALID: One of the inputs to a libnomp function call are not valid.

NOMP_USER_MAP_PTR_IS_INVALID: Map pointer provided to libnomp is not valid.

NOMP_USER_MAP_OP_IS_INVALID: Map operation provided to libnomp is not applicable.

NOMP_USER_LOG_ID_IS_INVALID: Log id provided to libnomp is not valid.

NOMP_INITIALIZE_FAILURE: libnomp is already initialized.

NOMP_FINALIZE_FAILURE: Failed to finalize libnomp.

NOMP_PY_CALL_FAILURE: A python call made by libnomp failed.

NOMP_LOOPY_CONVERSION_FAILURE: Loopy conversion failed.

NOMP_LOOPY_KNL_NAME_NOT_FOUND: Failed to find loopy kernel.

NOMP_LOOPY_CODEGEN_FAILURE: Code generation from loopy kernel failed.

NOMP_LOOPY_GRIDSIZE_FAILURE: Code generation from loopy kernel failed.

NOMP_CUDA_FAILURE: libnomp CUDA operation failed.

NOMP_HIP_FAILURE: libnomp HIP operation failed.

NOMP_OPENCL_FAILURE: libnomp OpenCL operation failed.